Proposal: require Haddock comment for every new top-level function and type in GHC source code

[Mateusz Kowalczyk]

On 06/30/2014 04:19 PM, Richard Eisenberg wrote:
> Thanks, Johan, for starting this discussion.
> 
> I mostly agree with the proposal. However, one (at times, serious) drawback to using Haddock is that it means that editing comments can cause parse failures. The way the GHC build works, these failures may not be detected until the end of a hacking session (if I'm using, say, `make 2`, as I tend to do) and then can be hard to diagnose. I've actually been bitten by this when working on GHC.

You should never get a parse failure anymore, as of 2.14.x versions. At
worst, the comment will render in an ugly way but it will no longer
cause failures due to typos in comment syntax.

What might cause failures is if you put a Haddock comment where GHC
doesn't expect it to. This should be fixed in GHC parser.

If you don't want to mess around with pretty comments, all you have to
do is to turn your function comments from ‘-- ’ to ’-- |’ and suddenly
everyone else can benefit without source-diving.

> So, I have to ask: why use Haddock? Do folks read the Haddock docs for GHC? (I don't, but perhaps that's because the docs aren't so good right now.) Would it be acceptable to change this proposal not to require Haddock docs?

I read the generated Haddock docs. The advantage of Haddock over
something else here is that you can look at class instances, have
clickable links and so on. Having to navigate on Haddock pages and
reading the function docs elsewhere would be cluttered.

> Even if we decide to keep this proposal about Haddock docs specifically, I would strongly request that correct rendering of the Haddock docs not be scrutinized. At the end of a hacking session (which is hard enough to find time for, as is), I don't want to be expected to look through the generated HTML to make sure that my typewriter font and italics are rendering correctly. This is something of a corollary to Simon's comment about wanting to refer to Notes from Haddock comments -- I would want the Haddock output to be quite secondary to the proper documentation in the source code.
> 
> (Note that this "demotion" of the role of Haddock is certainly not my practice in released libraries! But, Haddock is much less useful in an application like GHC than in a library.)

GHC is also a library, I think it's unreasonable to expect people to
jump into source and manually tracking down all the comments (if any)
when they want to use GHC API.

> All that said, I do agree with the intent of this proposal and am happy to take on my part of the burden of documenting new (and perhaps some old) functions as I work. I have been very guilty of the "broken window" effect in not documenting new code.
> 
> Thanks,
> Richard
> 


-- 
Mateusz K.