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

At the risk of sounding redundantly redundant, I'd like to third this. My workflow for finding stuff in the GHC codebase is a mixture of grep and Hoogle. Searching Hoogle for "+ghc :: [TyVar] -> Type -> Type" is a huge timesaver, and Hoogle sends me to the generated haddock comments. Usually the haddocks themselves aren't there, but the "Source" link is a handy way to jump to the code and explore. So having actual haddock documentation would only help in this regard. The Notes are *great* for subtle issues with the implementation of some function, but it'd be nice to have some commentary on how to _use_ that function without having to understand how it works. On Mon, Jun 30, 2014 at 3:42 PM, Ben Gamari wrote:

David Luposchainsky writes:

...

Hey list,

I am strongly in favour of the proposal. As a pedestrian-level GHC contributor, the *vast* majority of my time is spent trying to figure out what certain things do, when the answer could be found in a one- or two-line comment above a definition.

I'd like to second this. As an occassional contributor, I find myself wading through a lot of code to deduce functions' purpose. While I'm often pleasantly surprised by the quality of the notes scattered about the code, per-definition Haddocks would fill in the many remaining gaps and provide a nice overview of each module.

I agree that enforcing the quality of the rendered Haddocks is unnecessary. Once the language has been written there are many contributors (such as myself) who can further clean up the formatting.

Cheers,

- Ben

_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs