New source documentation policy for GHC
Simon Peyton Jones
simonpj at microsoft.com
Tue Jul 15 14:40:58 UTC 2014
Great. Could you update the Coding style page?
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
After some discussion  we've decided to require Haddock comments for all top-level entities (i.e. functions, classes, and data types) in new  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  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 .
We're not adding any technical enforcement , to avoid extending the compile/validate cycle, instead rely on social enforcement; please encourage people to write comments and remind them during code review!
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...
More information about the ghc-devs