Documentation design

[Isaac Dupree]

(for reference, here's the blog-post I wrote that inspired me to ask 
this list for advice.  I'll explain everything in this email anyway though.
http://haddock2009.wordpress.com/2009/06/23/how-to-navigate-your-code/
)

My challenge: getting to know an existing code-base quickly and easily,
so that I can hack on it.  Haddock and HsColour are already pretty
helpful at this, but they could be more helpful.  (haddock with
--ignore-all-exports, i.e. cabal haddock --internal, especially)

My dream situation: both haddock-pages and hscolour-pages would be
super-hyperlinked and super-readable.  For example, haddock would list
all a module's definitions, not just its exports. In HsColoured source,
every identifier would link to its definition or the haddockumentation
of its definition. and so forth.  It would be so much easier to generate
and browse this in HTML, than to get an IDE working, and it would be so
much more readable than a mere text-editor (even with syntax hilighting) 
and quicker clicking on hyperlinks than grepping for everything.

Actually I don't have the resources to worry about designing any 
HsColour stuff right now (its current design is mainly just a lexeme 
highlighter).  But, with your advices, I can design an improvement on 
Haddock's ignore-exports mode, which currently has a few shortcomings:
1. you can't tell which identifiers in a module are exported
2. it doesn't document a module's re-exports at all
3. it still obeys {-# OPTIONS_HADDOCK hide #-} et al, even when they're 
not appropriate for reading documentation of internals
4. 2+3 means that some things may be found nowhere in the documentation 
at all!  Not quite satisfying for something invoked by `cabal haddock 
--internal`.

(Here's a haddock-generated page you can look at so you can figure out 
the formatting-details I'll be describing:
http://www.haskell.org/ghc/docs/latest/html/libraries/base/Data-List.html
and its source code
http://www.haskell.org/ghc/docs/latest/html/libraries/base/src/Data-List.html
)

The ideal haddockumentation-formatting for this purpose isn't quite 
obvious though.  For example, sometimes you want to think about a module 
in terms of its abstract interface, but sometimes you want to figure out 
how it's implemented (without reverting completely to text based code 
browsing).  Maybe a compromise of some sort would be good.  so...

Here's a proposal, for a new mode (`haddock --all-internal`?, to be 
invoked by `cabal haddock --internal` rather than --internal's current 
effect of ignore-all-exports) :

Files with no explicit export list can be treated as-is anyway.

For all files that have an explicit export list, generate the
synopsis-of-exports near the top, as usual.  But have the index link,
generally, to where functions are originally defined (modulo being from
a non-internally-documented separate package, where it should link to
the appropriate place), and have the fuller documentation below be a
compilation of the identifiers *defined* in this module.

Actually that would need some revision because the sections and
subsections -- *, -- **, etc. defined in the export-list in the .hs,
actually are displayed
1. above the table of contents, linking to places in
2. the full list of definitions.  Which might be defined in the module
in a different order than they're listed in the export list.
Why not add the sections into the synopsis?  In this case, instead of 
adding them to the main doc section.  But hmm... in ordinary 
non-internal documentation, would it be nice to *additionally* have the 
sections marked in the synopsis (in addition to in the Contents and in 
the main docs section)?

Maybe this mode should also abstain from "hiding" any module, because 
that would cause missing docs. Etc.

Questions? Comments? Opinions? Does anyone want this feature, and/or not 
think it's particularly useful?

-Isaac