Scrap your boilerplate (but don't scrap them precious comments)
benjamin.franksen at bessy.de
Mon Feb 28 19:11:04 EST 2005
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
IMHO, a lot of this could and should be part of the (haddock-generated)
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
More information about the Glasgow-haskell-users