Proposal: require Haddock comment for every new top-level function and type in GHC source code

[Howard B. Golden]

I don't think this is mutually exclusive with Johan's proposal. Let me suggest an amendment: Developers (both new and old) would be encouraged to submit patches adding or improving documentation in the source code. Documentation patches would be vetted as any others would be.

Discouraging source code comments is the worst legacy of Unix. IMO (contradicting K&R) even incorrect comments are better than none.


Howard
________________________________
From: David Fox <dsf at seereason.com>
To: Johan Tibell <johan.tibell at gmail.com> 
Cc: "ghc-devs at haskell.org" <ghc-devs at haskell.org> 
Sent: Friday, June 27, 2014 6:26 AM
Subject: Re: Proposal: require Haddock comment for every new top-level function and type in GHC source code

I would counter propose a place on hackage for people to type in or modify the documentation for functions, designed in such a way that the documentation would easily find its way back into the project's source code (with developer approval.)  This way the documentation can be generated by people who only recently came to understand the function, so the questions a newcomer has are fresh in their mind.