Documenting gread / GReadS

[infinity0]

I think it would make things clearer to document gread as being in continuation-passing style. I literally only just realised this now, because it was similar to some other code I wrote today. And now I finally understand that type GReadS t [*] is something that consumes the continuation, which is vital to understanding how to implement an instance of GRead. (Previously I was just copy-pasting the existing instances and fiddling around until the type errors went away.)

[*] Actually this refers to the previous implementation of GReadResult, today's implementation avoids CPS and is a bit clearer, however the docstring still refers to the old CPS implementation which could still confuse users.

gread is still in CPS though and should be documented as such. Also, an alternative offering which may be more convenient for some users would be:

{-# LANGUAGE QuantifiedConstraints #-}

newtype SomeCxt c = SomeCxt { unCxt :: forall v. c v => v }

greadC
  :: (GRead t, forall a. c (t a))
  => Proxy t
  -> String
  -> SomeCxt c
greadC = ...

This relies on there existing an appropriate instance that applies to all a, which may not always exist, but if it does then it could be more convenient to use than passing in a continuation.

[phadej]

I added appropriate labels to this issue.