Already done. See "Comments on top-level entities".
On Tue, Jul 15, 2014 at 4:40 PM, Simon Peyton Jones <simo...@microsoft.com> wrote: > 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-boun...@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. >
_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs