
Hi, I have been racking my brain over the infamous 'gfoldl' and 'gunfold' combinators. (Yes, I have read the papers). What finally made me understand how they worked was reading the code: first the implementation of the gmap functions (Data/Generics/Basics.hs), then the long and detailed comments in the same file, and finally the instance definitions for the built-in types (in Data/Generics/Instances.hs). IMHO, a lot of this could and should be part of the (haddock-generated) documentation. It is such a waste: all these wonderful comments in the source file, that could be added to the docs with a keystroke! Instead, they simply say "Left-associative fold operation for constructor applications" which is really a bit terse for gfoldl, of which the source file comment (rightly) states that its type is a "headache". Furthermore, (example) implementations can sometimes be extremely helpful to understand things; this is especially true for a language like Haskell, in which the implementation is often already the shortest (or at least a very short) and most precise way to specify a functions semantics. In this case, the implementations of gfoldl helped me to understand what the function itself does. However, how and why these extremely abstract combinators can serve as the basic building blocks of all the more concrete and better understandable variants is best documented by the implementation of just these variants gmapXX and friends. (Maybe one or two examples implementations would suffice). At least, it should be stated in the docs what the type constructor ('c') is in each case. I don't know if haddock can add the implementation of a function to the documentation. If not, such a feature should be considered. SYB is a wonderful piece of work and deserves to be documented as well as it is programmed. Ben