RFC: hyperlinks in Haddock docs

[Duncan Coutts]

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
> it.
> 
> 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:

[snip]

> 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
module Graphics.UI.Gtk.Types.

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:
http://www.haskell.org/haddock/docs/module-attributes.html

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
definition here".

Duncan