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

[Johan Tibell]

On Fri, Jun 27, 2014 at 12:17 PM, Simon Peyton Jones
<simonpj at microsoft.com> wrote:
> I’d be OK with this, (it’s a bit like requiring signatures on all top level functions) but I don’t know how we’d enforce it.

I think social enforcement is enough. If we agree that this is
something we want to do and communicate that to ghc-devs@, put a note
in our style guide, and kindly remind people to add comments when we
do code reviews, we'll eventually end up with a culture of writing
Haddocks.

I think the most important part right now is that current contributors
agree that this is something we want to do.

Aside: people usually say that they find it hard to know what to
document in their own code, because they don't know what others will
find difficult. My advice is this: add a sentence or two about what
the function does and why it exists, no matter how obvious you think
that statement is.

> Do you think the requirement should be for all top-level functions or just exported ones?

I take what I can get, but I think documenting all top-level functions
makes sense in the case of GHC, as there's so much that goes on in our
modules but we often only export a handful of functions. For example,
compiler/codeGen/StgCmmPrim.hs is 2,000 lines long but only exports 3
functions. For someone that wants to work on that module for the first
time only have docs on those three functions is helpful, but likely
not enough. FWIW I document all top-level functions in my projects
(and when I don't I often regret it later).

> I agree that Notes have a different purpose.  But it should be OK style to refer to a Note from a top-level function comment, even though Haddock won’t be able to make much sense of it.

Sure. Personally I would refer to the note from the function body if
it talks mostly about the implementation, as opposed to how to use the
function.

-- Johan