Documentation design

[jutaro]

Have you tried Leksah? I guess it would help you a lot with your task.
Jürgen


Isaac Dupree-3 wrote:
> 
> (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
> 
> 
> 
> _______________________________________________
> Libraries mailing list
> Libraries at haskell.org
> http://www.haskell.org/mailman/listinfo/libraries
> 
> 

-- 
View this message in context: http://www.nabble.com/Documentation-design-tp24349398p24351949.html
Sent from the Haskell - Libraries mailing list archive at Nabble.com.