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

[Mateusz Kowalczyk]

On 06/27/2014 01:19 PM, Johan Tibell wrote:
> 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.

Notes could be moved into the module header if necessary so that they
are rendered by Haddock. Alternatively, one function can contain the
note and other places can refer to it by means of an anchor.

> -- Johan
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://www.haskell.org/mailman/listinfo/ghc-devs
> 

My personal gripe of trying to read docs for GHC modules/types is that
some older modules are in .lhs format which means we have to dive out of
nicely-rendered HTML and go into source. Was there ever talk of
converting Literate Haskell files into more Haddock-friendly format?

-- 
Mateusz K.