Cross referencing in Ddoc

[Sönke Ludwig]

Am 30.12.2013 21:58, schrieb Walter Bright:
>>> 2. Using the word S as a word, not in reference to symbol S, would
>>> generate a hyperlink which would not make sense.
>>
>> I've have seen that happened a couple of times with documentation
>> generators
>> that support it, it has never bother me. As Sönke has said, you can
>> solve that
>> by appending an underscore and the compiler would not create a link of
>> the symbol.
> 
> While possible, I'm not too enamored with this. It makes for a
> maintenance problem. Add a new symbol to a module, and then you have to
> manually search for any other instances of the word. Naturally, the
> latter won't get done, and you're left with nonsense links in the doc.
> 

True, but I'd argue that this is really the exception. New symbols also
influence just the documentation of the current scope (i.e. a new class
member won't affect the documentation of other classes in the same module).

> 
>>> 3. If there are multiple symbols S, hyperlinks to the wrong one would be
>>> created. This is worse than useless.
>>
>> Most of the times there are not multiple symbols with the same name, the
>> language make sure of that. Although there will be a problem with
>> function
>> overloading.
> 
> I've run into this a few times, and it cannot be dismissed easily.
> Worse, there is the issue of how one overrides the auto-link generation
> to be the right link.

Qualified names. The qualifying prefix could be hidden from the user or
displayed as is. But after all it also provides useful information to
the reader, as it's now possible to tell which symbol is meant without
following the link first.