Documentation design

[Isaac Dupree-3]

(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



_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe@...
http://www.haskell.org/mailman/listinfo/haskell-cafe

[Felipe Lessa]

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.
_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe@...
http://www.haskell.org/mailman/listinfo/haskell-cafe

[Peter Hercek-2]

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.

_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe@...
http://www.haskell.org/mailman/listinfo/haskell-cafe