On Fri, Jun 27, 2014 at 12:17 PM, Simon Peyton JonesI think social enforcement is enough. If we agree that this is
<simonpj@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.
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.
I take what I can get, but I think documenting all top-level functions
> Do you think the requirement should be for all top-level functions or just exported ones?
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).
Sure. Personally I would refer to the note from the function body if
> 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.
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