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.
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@haskell.org] On Behalf Of Johan Tibell Sent: 07 July 2014 08:39 To: ghc-devs@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.
Already done. See "Comments on top-level entities".
On Tue, Jul 15, 2014 at 4:40 PM, 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@haskell.org] *On Behalf Of *Johan Tibell *Sent:* 07 July 2014 08:39 *To:* ghc-devs@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.
participants (2)
-
Johan Tibell -
Simon Peyton Jones