Proposal: require Haddock comment for every new top-level function and type in GHC source code
dsf at seereason.com
Mon Jun 30 15:32:50 UTC 2014
On Fri, Jun 27, 2014 at 11:11 AM, Mateusz Kowalczyk <fuuzetsu at fuuzetsu.co.uk
> On 06/27/2014 03:26 PM, David Fox wrote:
> > I would counter propose a place on hackage for people to type in or
> > the documentation for functions, designed in such a way that the
> > documentation would easily find its way back into the project's source
> > (with developer approval.) This way the documentation can be generated
> > people who only recently came to understand the function, so the
> > 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...
More information about the ghc-devs