(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.htm... ) 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
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.htm... )
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@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.
participants (2)
-
Isaac Dupree -
jutaro