(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
I would also like some sort of "combo" mode for Hackage where the docs are shown the same way that they are now but with a link to "Internals" showing the view that you propose, perhaps showing only internals or highlighting them. Then we would be able to have the internal documentation on Hackage without polluting the most used exported docs. If you anybody doesn't like having to go on "Internals" they may 'cabal fetch' at will. -- Felipe.
I like your proposal. Few notes below. On Sun, 05 Jul 2009 23:45:31 -0400, Isaac Dupree wrote:
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.
You do not need to resort to grep for navigation of your source code from your text editor. At least not with vim. It has tags and stack of tags. Generate tags for your source code and use Ctrl-] to navigate to the definition (or Ctrl-W} to open the definition in preview window). Any jump to definition done with Ctrl-] is stored in the stack of tags. You can return to the previous position in the stack with Ctrl-T or return to the last next position with :tag. You can check how the tag stack looks like with :tags. This way you can navigate the stack of tags comfortably and the stack of tags can correspond to the lexical (creation) stack as it would exist during execution. The only problem with this is that it works so nicely only for me currently since I have a patch applied to ghci which makes ghci to include also the non-exported symbols to the tags file. I would like to add the patch to ghci but so far there is only small support for it. If you (or anybody else) would like it drop me a note or comment on the glasgow haskell users list: http://www.haskell.org/pipermail/glasgow-haskell-users/2009- June/017399.html The :ctags improvement patch gives you a substitute for intellisense in vim. I have ":inoremap ^] ^[^W}a" in .vimrc so when I start to type a function name I can finish it with some completion, and (while still being in the insert mode) I can get help for it to the preview window with Ctrl-].
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.
I like it but some notes to the new synopsis part: You mean the index link for a symbol should go to the haddock help page not to the HsColour source page. Right? I would like some annotations aligned to the right which would indicate whether the symbol is defined locally or it is reexported. There should be also an annotation or different font to indicate whether the symbol in synopsis is exported or not (in addition to nonexported symbols being is a separate section). This is so that one can easily see what part of the help is shown.
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)?
Not sure I understand this part well. I assume by main document part you mean the part with detailed description and source code links. I want the contents preserved with the added last section with name "Nonexported symbols", or something named like that. Adding the section names to synopsis seems like good idea to me. In such a case it could be removed from the main doc part but I would rather keep it there. But I do not really mind either way. I assume the main doc part would contain only the symbols defined in the given module (not the re-exported ones). But the synopsis part would contain the names of re-exported symbols with links to the appropriate location in the main doc part of the module where the symbol is really defined. Also the main doc part would contain one more section "Nonexported symbols" with help for the symbols defined in the module but not exported. I would also like "back-links": clicking on the bold symbol name (which currently does not have any hyperlink) in the main doc part would open a pop up list box with all the symbols using/calling it within the project. Selecting an item from the pop up list box would navigate to the main doc part where the caller symbol is described. Peter.
participants (3)
-
Felipe Lessa -
Isaac Dupree -
Peter Hercek