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

[Simon Marlow]

Including the source code in Haddock output is a good idea.  Retaining
the original indentation would be tricky (but possible, the HaRe folks
have to solve a similar problem).  

Marking up the source code with hyperlinks requires applying Haskell's
static scoping rules to the source code - currently Haddock doesn't have
to do this, it only deals with type signatures and type declarations.

One thing I'm going to do for the 6.4 docs is include a link to the
source code file (pointing to cvs.haskell.org) for each module.

Cheers,
	Simon

On 01 March 2005 01:20, Ralf Lammel wrote:

> 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
> _______________________________________________
> Glasgow-haskell-users mailing list
> Glasgow-haskell-users at haskell.org
> http://www.haskell.org/mailman/listinfo/glasgow-haskell-users