library documentation comments and contributions (was [Haskell-cafe] Comments from OCaml Hacker Brian Hurt)

[Claus Reinke]

> 2) the Haskell docs _don't_ do good enough a job at giving intuition
> for what math terms mean
> 
> If we fix #2, then #1 is no longer a problem, yes?
> 
> For you folks who work on GHC, is it acceptable to open tickets for
> poor documentation of modules in base?  I think leaving the
> documentation to the tragedy of the commons isn't the best move, but
> if even a few of us could remember to open tickets when new
> Haskell'ers complain about something being confusing then it could be
> on _someone's_ docket.

I can't find the thread at the moment, but this has been discussed
before, and my recollection is that wikis were to be used to accumulate
documentation comments and updates (there also was some discussion
about the best format for comment patches, but getting content was
thought to be more important). So, there would be a subset of the
Haskell wiki for the base library, and package-specific wiki locations
for their documentations.

Haddock already seems to provide the necessary support:

    http://www.haskell.org/haddock/doc/html/invoking.html

    --comments-base=URL , --comments-module=URL , --comments-entity=URL 

    Include links to pages where readers may comment on the documentation. 
    This feature would typically be used in conjunction with a Wiki system.

    Use the --comments-base option to add a user comments link in the header 
    bar of the contents and index pages. Use the --comments-module to add a 
    user comments link in the header bar of each module page. Use the 
    --comments-entity option to add a comments link next to the documentation 
    for every value and type in each module. 

    In each case URL is the base URL where the corresponding comments page 
    can be found. For the per-module and per-entity URLs the same substitutions 
    are made as with the --source-module and --source-entity options above.

    For example, if you want to link the contents page to a wiki page, and every 
    module to subpages, you would say haddock --comments-base=url 
    --comments-module=url/%M

So it seems it is only a question of actually using these options with
suitably prepared per-package documentation wikis, and improving
the documentation or asking for clarifications would be almost as easy
as emailing here!-) And if everyone who stumbles over a documentation
problem puts the solution on the wiki, documentation should improve
quickly (there is still the issue of selecting wiki improvement suggestions
for inclusion in the "real" documentation).

Does anyone know why these options are not in use already?

Claus