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

[Andrew Farmer]

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 <bgamari.foss at gmail.com> wrote:
> 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
>
>
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://www.haskell.org/mailman/listinfo/ghc-devs
>