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

[Ben Gamari]

David Luposchainsky <dluposchainsky at googlemail.com> 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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 472 bytes
Desc: not available
URL: <http://www.haskell.org/pipermail/ghc-devs/attachments/20140630/c8576ab1/attachment.sig>