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: [EMAIL PROTECTED] >> [mailto:glasgow-haskell- [EMAIL PROTECTED] 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, >> 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@haskell.org >> http://www.haskell.org/mailman/listinfo/glasgow-haskell-users > _______________________________________________ > Glasgow-haskell-users mailing list > Glasgow-haskell-users@haskell.org > http://www.haskell.org/mailman/listinfo/glasgow-haskell-users _______________________________________________ Glasgow-haskell-users mailing list Glasgow-haskell-users@haskell.org http://www.haskell.org/mailman/listinfo/glasgow-haskell-users