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

[Mateusz Kowalczyk]

On 06/27/2014 03:26 PM, David Fox wrote:
> I would counter propose a place on hackage for people to type in or modify
> the documentation for functions, designed in such a way that the
> documentation would easily find its way back into the project's source code
> (with developer approval.)  This way the documentation can be generated by
> people who only recently came to understand the function, so the questions
> a newcomer has are fresh in their mind.
> 

Are you asking for a wiki-like thing for documentation? There were a few
times where this has been proposed such as
https://github.com/haskell/haddock/issues/72 but in general it turns out
that there's not enough interest for anyone to sit down and implement it
and make sure it all works properly. Patches should be going straight to
upstream rather than lingering on Hackage until someone notices them
(even with automated tools, it's a pain). I doubt many people would use
it for anything but typos because if you have enough knowledge about a
function to document it, you're likely to already be involved with the
project in some way and have means to report it properly.

> 
> On Fri, Jun 27, 2014 at 4:19 AM, Johan Tibell <johan.tibell at gmail.com>
> wrote:
> 
>> On Fri, Jun 27, 2014 at 12:17 PM, Simon Peyton Jones
>> <simonpj at microsoft.com> wrote:
>>> I’d be OK with this, (it’s a bit like requiring signatures on all top
>> level functions) but I don’t know how we’d enforce it.
>>
>> I think social enforcement is enough. If we agree that this is
>> something we want to do and communicate that to ghc-devs@, put a note
>> in our style guide, and kindly remind people to add comments when we
>> do code reviews, we'll eventually end up with a culture of writing
>> Haddocks.
>>
>> I think the most important part right now is that current contributors
>> agree that this is something we want to do.
>>
>> Aside: people usually say that they find it hard to know what to
>> document in their own code, because they don't know what others will
>> find difficult. My advice is this: add a sentence or two about what
>> the function does and why it exists, no matter how obvious you think
>> that statement is.
>>
>>> Do you think the requirement should be for all top-level functions or
>> just exported ones?
>>
>> I take what I can get, but I think documenting all top-level functions
>> makes sense in the case of GHC, as there's so much that goes on in our
>> modules but we often only export a handful of functions. For example,
>> compiler/codeGen/StgCmmPrim.hs is 2,000 lines long but only exports 3
>> functions. For someone that wants to work on that module for the first
>> time only have docs on those three functions is helpful, but likely
>> not enough. FWIW I document all top-level functions in my projects
>> (and when I don't I often regret it later).
>>
>>> I agree that Notes have a different purpose.  But it should be OK style
>> to refer to a Note from a top-level function comment, even though Haddock
>> won’t be able to make much sense of it.
>>
>> Sure. Personally I would refer to the note from the function body if
>> it talks mostly about the implementation, as opposed to how to use the
>> function.
>>
>> -- Johan
>> _______________________________________________
>> ghc-devs mailing list
>> ghc-devs at haskell.org
>> http://www.haskell.org/mailman/listinfo/ghc-devs
>>
> 
> 
> 
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://www.haskell.org/mailman/listinfo/ghc-devs
> 


-- 
Mateusz K.