RFC: hyperlinks in Haddock docs

[Simon Marlow]

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:

  - A is better than B if A directly or indirectly imports B

But this isn't quite good enough: for example the Prelude re-exports a
lot of stuff, but when linking Maybe for example, we probably want to
link to Data.Maybe.Maybe rather than Prelude.Maybe.  But the Prelude is
the right place to get Int and String from.

I don't particularly want the programmer to have to say for each entity
where the best place to get it from is, much better would be to have a
per-module flag that says "this module is a good/bad link destination".
Perhaps we actually want to give an integer priority in each module.

Thoughts?  Better ideas?

Cheers,
	Simon