ANN: New source documentation policy for GHC

[Johan Tibell]

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/20140707/68c24be9/attachment.html>