broken links

[Simon Marlow]

On 09 December 2004 19:09, Ross Paterson wrote:

> On Thu, Dec 09, 2004 at 05:29:45PM -0000, Simon Marlow wrote:
>> Thanks.  Data.Array.Base is a "hidden" module - we don't expose its
>> documentation, but unfortunately Haddock sometimes still generates
>> links to it, when it can't find anywhere better to link to.  This is
>> a bug, but unfortunately it's a pretty deep bug - Haddock would need
>> to be able to link to modules outside the imported scope of the
>> current module, which it currently can't do. 
>> 
>> Fortunately there's often a workaround in the form of rearranging the
>> imports of a module to expose the correct linking destinations to
>> Haddock.  I'll do a sweep over the docs before we release GHC 6.4 and
>> make sure we don't have any dangling links of this kind.
> 
> It's often instances from other modules that are the culprits, and
> they're quite hard to fix.

Yes, that's true.

I've been thinking of a solution along these lines:  Haddock processes
the modules in two phases.  The first phase resolves all the names and
determines the "definitive" documentation for each entity.  The second
phase makes all the links point to the definitive documentation, with
certain exceptions: if the entity is also documented in the local
module, then point there instead.  Perhaps there are other exceptions.
We might need a way to indicate "definitive", or maybe just the
module(s) furthest up the dependency tree would do.

Cheers,
	Simon