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

[David Fox]

On Fri, Jun 27, 2014 at 11:11 AM, Mateusz Kowalczyk <fuuzetsu at fuuzetsu.co.uk
> wrote:

> 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.
>
>
My thought was that it would end up in the library's source code, not that
it would reside in a wiki.  The question is whether anyone has the
motivation to write a sufficiently smooth mechanism to achieve this.  If I
was editing a package that I normally upload to hackage and I could look at
a nice presentation of alternative documentation strings people have
suggested for the different functions in my library, I would be happy to
cut and paste them into the source code.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/ghc-devs/attachments/20140630/b6610e9a/attachment-0001.html>