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 _______________________________________________ Glasgow-haskell-users mailing list Glasgow-haskell-users@haskell.org http://www.haskell.org/mailman/listinfo/glasgow-haskell-users
