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

[David Fox]

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 <johan.tibell at gmail.com>
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.
>
> -- Johan
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://www.haskell.org/mailman/listinfo/ghc-devs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/ghc-devs/attachments/20140627/59c358d8/attachment.html>