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