Scrap your boilerplate (but don't scrap them precious comments)

[Benjamin Franksen]

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