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. On Fri, Jun 27, 2014 at 4:19 AM, Johan Tibell wrote:

On Fri, Jun 27, 2014 at 12:17 PM, Simon Peyton Jones 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 _______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs