Scrap your boilerplate (but don't scrap them precious comments)
simonmar at microsoft.com
Tue Mar 1 04:42:17 EST 2005
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.
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.
>> -----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
>> 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
>> 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.
>> Glasgow-haskell-users mailing list
>> Glasgow-haskell-users at haskell.org
> Glasgow-haskell-users mailing list
> Glasgow-haskell-users at haskell.org
More information about the Glasgow-haskell-users