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