Scrap your boilerplate (but don't scrap them precious comments)
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.
> -----Original Message-----
> From: glasgow-haskell-users-bounces at haskell.org
> 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
> I have been racking my brain over the infamous 'gfoldl' and 'gunfold'
> combinators. (Yes, I have read the papers). What finally made me
> how they worked was reading the code: first the implementation of the
> functions (Data/Generics/Basics.hs), then the long and detailed
> the same file, and finally the instance definitions for the built-in
> (in Data/Generics/Instances.hs).
> IMHO, a lot of this could and should be part of the
> 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
> (rightly) states that its type is a "headache".
> Furthermore, (example) implementations can sometimes be extremely
> understand things; this is especially true for a language like
> which the implementation is often already the shortest (or at least a
> short) and most precise way to specify a functions semantics.
> In this case, the implementations of gfoldl helped me to understand
> function itself does. However, how and why these extremely abstract
> combinators can serve as the basic building blocks of all the more
> and better understandable variants is best documented by the
> of just these variants gmapXX and friends. (Maybe one or two examples
> implementations would suffice). At least, it should be stated in the
> what the type constructor ('c') is in each case.
> I don't know if haddock can add the implementation of a function to
> documentation. If not, such a feature should be considered.
> SYB is a wonderful piece of work and deserves to be documented as well
> is programmed.
> Glasgow-haskell-users mailing list
> Glasgow-haskell-users at haskell.org
More information about the Glasgow-haskell-users