[Haskell-cafe] Re: Documentation design

[Peter Hercek]

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.