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

[John Meacham]

On Mon, Feb 28, 2005 at 05:20:18PM -0800, 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.

Yeah, I have wanted some special haddock identifier which means 'include
the body of the function here'. Since often, this can be the best
documentation. 

        John

-- 
John Meacham - ⑆repetae.net⑆john⑈