Hi,<br><br>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.<br>
<br>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:<br>
<br><blockquote style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex; font-family: courier new,monospace;" class="gmail_quote">-- The Data instance for Array preserves data abstraction at the cost of <br>
-- inefficiency. We omit reflection services for the sake of data abstraction.<br>instance (Typeable a, Data b, Ix a) => Data (Array a b)<br> where<br> gfoldl f z a = z (listArray (bounds a)) `f` (elems a)<br> toConstr _ = error "toConstr"<br>
gunfold _ _ = error "gunfold"<br> dataTypeOf _ = mkNorepType "Data.Array.Array"<br></blockquote><br><br>Cheers,<br>Pedro<br><br>[1] <a href="http://www.comlab.ox.ac.uk/publications/publication1385-abstract.html">http://www.comlab.ox.ac.uk/publications/publication1385-abstract.html</a><br>
<br><div class="gmail_quote">On Sun, Oct 11, 2009 at 14:58, John Lato <span dir="ltr"><<a href="mailto:jwlato@gmail.com">jwlato@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
For anyone writing introductions to generic programming, take this as<br>
a plea from Haskellers everywhere. If one of the RWH authors can't<br>
understand how to make use of these techniques, what hope do the rest<br>
of us have?<br>
<br>
John Lato<br>
<br>
P.S. Some might wryly note that I'm the maintainer of a package which<br>
is also known for incomprehensible documentation. To which I would<br>
reply that our effort is much newer, I consider it a problem, and it's<br>
being worked on, contrasted to the state of GP where similarly<br>
impenetrable documentation has been and continues to be the norm.<br>
<br>
><br>
> From: "Bryan O'Sullivan" <<a href="mailto:bos@serpentine.com">bos@serpentine.com</a>><br>
><br>
> I think maybe someone else will have to take a crack at a Data instance for<br>
> Text, because the documentation for Data.Data is not written in English. In<br>
> its syntax and structure, it closely hews to what we think of as English,<br>
> but it is the kind of documentation that can only be understood by someone<br>
> who already knows what it is going to say.<br>
><br>
> This is an exemplar of my experience with the cottage industry of generic<br>
> programming in Haskell: I'd really quite like to use the stuff, but for<br>
> goodness's sake, o beloved researchers, please aim your expository papers at<br>
> non-specialists once in a while. An endless chain of papers of the form "my<br>
> technique, which you won't understand, is better than this other technique,<br>
> which you haven't read about and won't anyway understand, in subtle ways<br>
> that you won't understand" does not feel to me like progress.<br>
><br>
> Yours in some misery and frustration,<br>
> Bryan.<br>
_______________________________________________<br>
Haskell-Cafe mailing list<br>
<a href="mailto:Haskell-Cafe@haskell.org">Haskell-Cafe@haskell.org</a><br>
<a href="http://www.haskell.org/mailman/listinfo/haskell-cafe" target="_blank">http://www.haskell.org/mailman/listinfo/haskell-cafe</a><br>
</blockquote></div><br>