On Mon, Nov 08, 2010 at 11:16:59PM -0500, wren ng thornton wrote:
I believe the suggestion was not to add hyperlinks automatically, but rather to *remove* them automatically. For example, with such automation I can just write 'Int', 'Foo', or 'Local.Bar' everywhere and leave it up to Haddock to ensure properties like only the first one actually being a link.
One reason this would be beneficial is that it means we wouldn't have to stop and think about whether a given identifier has already been linked for this page, let alone maintain the firstness quality when we decide to rearrange the order in which things occur. Automating things like firstness is the only reliable way to be consistent about it, just like when giving citations in papers (e.g., many LaTeX packages will Do The Right Thing).
And because haddock moves documentation between modules, it's often impossible to distinguish in the source which is the first use of a name in the modules in which it's used.