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

Ralf Lammel ralfla at microsoft.com
Mon Feb 28 20:20:18 EST 2005


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

> -----Original Message-----
> From: glasgow-haskell-users-bounces at haskell.org
[mailto:glasgow-haskell-
> users-bounces at haskell.org] On Behalf Of Benjamin Franksen
> Sent: Monday, February 28, 2005 4:11 PM
> To: glasgow-haskell-users at 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,
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
> _______________________________________________
> Glasgow-haskell-users mailing list
> Glasgow-haskell-users at haskell.org
> http://www.haskell.org/mailman/listinfo/glasgow-haskell-users


More information about the Glasgow-haskell-users mailing list