-----Original Message----- From: glasgow-haskell-users-bounces@haskell.org [mailto:glasgow-haskell- users-bounces@haskell.org] On Behalf Of Benjamin Franksen Sent: Monday, February 28, 2005 4:11 PM To: glasgow-haskell-users@haskell.org Subject: Scrap your boilerplate (but don't scrap them precious comments)

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,

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

That's a very good point. Me too, I would often wish to see some principled code details when entering documentation. For instance what is the point of _explaining_ that "inc" aliases "add 1", why not just show that equation! I agree that gmap?? are a bit of this kind. It is so much easier to explain them, while showing code. It is so much of a hassle to explain them while not showing code. The implementations of gmap?? are almost like algebraic properties ... I mean these are rather principled implementations. A documentation tool should support algebraic laws _and_ such principled implementations. It would really help to link the function signatures with the function definitions in the sense of a limited code browsing functionality. I am sure this is not a new discussion topic, but we really need this IMHO. Ralf that 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 _______________________________________________ Glasgow-haskell-users mailing list Glasgow-haskell-users@haskell.org http://www.haskell.org/mailman/listinfo/glasgow-haskell-users