Hi,

While I agree that the documentation of Data.Generics is not perfect, I do not think it is possible to have the haddock documentation be self-contained. For a thorough understanding of syb, a user has to read the two initial papers, which are linked from the haddock documentation. I also do not think it's reasonable to explain all the details beyond monads in the Control.Monad haddock, for instance.

For the problem at hand (a Data instance for Text), I can only say that generic programming and abstract datatypes do not mix too well (although there is work on the area, see [1]). Generics work by exploiting the structure of types, and if that structure is explicitly kept hidden then (rather ad hoc) workarounds have to be used. See, for example, the Data instance for Array:

-- The Data instance for Array preserves data abstraction at the cost of
-- inefficiency. We omit reflection services for the sake of data abstraction.
instance (Typeable a, Data b, Ix a) => Data (Array a b)
 where
  gfoldl f z a = z (listArray (bounds a)) `f` (elems a)
  toConstr _   = error "toConstr"
  gunfold _ _  = error "gunfold"
  dataTypeOf _ = mkNorepType "Data.Array.Array"


Cheers,
Pedro

[1] http://www.comlab.ox.ac.uk/publications/publication1385-abstract.html

On Sun, Oct 11, 2009 at 14:58, John Lato <jwlato@gmail.com> wrote:
For anyone writing introductions to generic programming, take this as
a plea from Haskellers everywhere.  If one of the RWH authors can't
understand how to make use of these techniques, what hope do the rest
of us have?

John Lato

P.S. Some might wryly note that I'm the maintainer of a package which
is also known for incomprehensible documentation.  To which I would
reply that our effort is much newer, I consider it a problem, and it's
being worked on, contrasted to the state of GP where similarly
impenetrable documentation has been and continues to be the norm.

>
> From: "Bryan O'Sullivan" <bos@serpentine.com>
>
> I think maybe someone else will have to take a crack at a Data instance for
> Text, because the documentation for Data.Data is not written in English. In
> its syntax and structure, it closely hews to what we think of as English,
> but it is the kind of documentation that can only be understood by someone
> who already knows what it is going to say.
>
> This is an exemplar of my experience with the cottage industry of generic
> programming in Haskell: I'd really quite like to use the stuff, but for
> goodness's sake, o beloved researchers, please aim your expository papers at
> non-specialists once in a while. An endless chain of papers of the form "my
> technique, which you won't understand, is better than this other technique,
> which you haven't read about and won't anyway understand, in subtle ways
> that you won't understand" does not feel to me like progress.
>
> Yours in some misery and frustration,
> Bryan.
_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe