RFC: hyperlinks in Haddock docs
duncan.coutts at worc.ox.ac.uk
Tue Feb 22 12:45:39 EST 2005
On Tue, 2005-02-01 at 11:02 +0000, Simon Marlow wrote:
> I'm making some changes to the way Haddock creates links, and I'd like
> to solicit comments on possible alternatives.
> The existing approach is for each non-locally-defined identifier in the
> current module, we hyperlink to a module that it was imported from, and
> that (a) actually documents the identifer, and (b) isn't hidden.
> There are some problems with the existing approach. It doesn't cope
> well with instances: instances might refer to types/classes not below
> the current module in the hierarchy. Also you might import an entity
> from a "hidden" module, but actually want to hyperlink to another module
> in the hierarchy, not below the current one. Hyperlinking in the
> documentation doesn't follow the module import hierarchy, and nor should
> So the new approach is to try to build up a global table of the "best"
> destinations to link to for each entity. The question is how to
> determine "best". Here's my first stab:
> Thoughts? Better ideas?
Let me throw in another example:
In gtk2hs we have one huge module which defines all the types (this is
produced by a code generator from a text file which describes the Gtk+
class hierarchy). However we don't ever want this module to be exposed
to users. We re-export each data type corresponding to the Gtk+ class in
it's one module (which wraps all the methods of the class). Eg the
module Graphics.UI.Gtk.Buttons.Button re-exports 'Button' from the
So in other modules we say 'Button' for example but this gets linked to
the huge hierarchy module rather than the re-export from the button
module. So we have taken to linking to the module itself, ie using
"Button" however this is no longer a nice solution now that we are using
hierarchical modules names since we have to say
"Graphics.UI.Gtk.Buttons.Button" which no longer flows very well in the
middle of a sentence.
The difficulty with this example is that our source module which
contains a reference 'Buttton' does not actually import the module
through which it is re-exported (indeed if we consistently did this I
think we would get cyclic module deps).
As an aside: we have not been able to get any of the module attributes
#hide, prune, ignore-exports to work as described:
So we would be happy to add some haddock declarations saying "do not
link here!" or "please link here".
For example we would say #hide in Graphics.UI.Gtk.Types (and we'd want
that to mean never ever generate links to this module) and in each
module that re-exports (and documents) each Gtk+ class add a haddock
declarations saying "for references to X please always link to its
More information about the Glasgow-haskell-users