New source documentation policy for GHC

[Johan Tibell]

Already done. See "Comments on top-level entities".


On Tue, Jul 15, 2014 at 4:40 PM, Simon Peyton Jones <simonpj at 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-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/dbaa0bc7/attachment.html>