New source documentation policy for GHC

[Simon Peyton Jones]

Dear Johan

Great.  Could you update the Coding style page?
https://ghc.haskell.org/trac/ghc/wiki/Commentary/CodingStyle


Simon

From: ghc-devs [mailto:ghc-devs-bounces at haskell.org] On Behalf Of Johan Tibell
Sent: 07 July 2014 08:39
To: ghc-devs at haskell.org
Subject: ANN: New source documentation policy for GHC

Hi all!

After some discussion [1] we've decided to require Haddock comments for all top-level entities (i.e. functions, classes, and data types) in new [2] GHC code. If you're writing new code, please try to add at least a sentence of two documenting what the function does and why. When you're reviewing patches, please ask the author to add comments.

This policy doesn't replace GHC's use of [Notes], which talk mostly about implementation details, but instead compliments it by making it clearer how to *use* the code. See the original thread [1] for some example comments.

We will use Haddock for our comments, in order to make the generated Haddock docs more useful, but we don't require that you use any special markup in the comments themselves or required that you validate that your docs render nicely [3].

We're not adding any technical enforcement [4], to avoid extending the compile/validate cycle, instead rely on social enforcement; please encourage people to write comments and remind them during code review!

Cheers,
  Johan

1. https://www.mail-archive.com/ghc-devs@haskell.org/msg05135.html
2. Documenting old code is of course also much appreciated!
3. This is a pragmatic trade-off to not add too much extra work for frequent contributions. It's easy for anyone to fix up bad markup, so allowing some bad markup to slip in temporarily isn't a big issue.
4. We might try to add lint warning to Phabricator, to serve as an extra reminder to patch authors.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/ghc-devs/attachments/20140715/bb777679/attachment.html>