[Haskell-cafe] Package documentation complaints -- and a suggestion

[wren ng thornton]

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.

-- 
Live well,
~wren