[Haskell-cafe] Package documentation complaints -- and a suggestion
wren ng thornton
wren at freegeek.org
Tue Oct 25 04:34:22 CEST 2011
On 10/24/11 12:34 PM, Gregory Collins wrote:
> Examples could include: "Your package lacks a description", "more than
> X% of your modules lack toplevel module comments", "fewer than Y% of
> your toplevel exports have haddock comments", etc... Packages with
> stability=experimental would probably be exempt from the requirements.
I'm not so sure about that exemption. The "experimental" stability level
seems to be the norm on Hackage and often means "I use this for real
projects, but because I use it for real projects I'm not quite willing
to hammer the API in stone just yet". Surely we should distinguish this
level of stability from "no seriously I'm just goofing around with
category theory", but unfortunately both classes of project are called
"experimental". While the latter may deserve a pass (to encourage
goofing around with category theory :), the lack of documentation for
the former seems to me like the main motivation for instituting such an
automatic system in the first place.
Before dealing with automatic documentation requirements, perhaps it'd
be better to develop a standard consensus on the terms used in the
stability field and actively advocating for people to adopt it, as was
done with the PVP.
More information about the Haskell-Cafe