Cross referencing in Ddoc

[Sönke Ludwig]

Am 30.12.2013 20:08, schrieb Walter Bright:
> On 12/29/2013 9:38 AM, Jacob Carlborg wrote:
>> A. Automatic cross reference
>>
>> Automatically create links for all matching symbols in the current
>> scope. That
>> means to create a link to a symbol in the current scope it's enough to
>> mention
>> it's name in the documentation.
> 
> This will create many unwanted links, in three scenarios:
> 
> 1. In the description for S, there should not be hyperlinks to S. These
> would be annoying - when you click on them, nothing will happen.

This one can easily be implemented by the documentation generator.

> 
> 2. Using the word S as a word, not in reference to symbol S, would
> generate a hyperlink which would not make sense.

The _S scheme can be used to avoid the hyperlink.

> 
> 3. If there are multiple symbols S, hyperlinks to the wrong one would be
> created. This is worse than useless.

If the same lookup rules are used as for the D code itself, the results
should turn out pretty much as expected. DDOX currently doesn't follow
imports correctly, yet, but even with just a simple hierarchical lookup
in the current scope and a fallback to a global lookup (across all
symbols) this seems to work pretty well.

> 
> In my adding of such hyperlinks, 1..3 happen regularly, this is not a
> "may" happen. It's a "will" happen, a lot.
> 

It will happen, but you have to weigh disabling these places manually
against having to add an explicit link every time. From what I've seen
so far, the latter means a *lot* more work.

Personally, I'd prefer an explicit, but unobtrusive, marker like Doxygen
uses (e.g. "func()", "::func" or "#func" are recognized as cross
references). But since the _ rule is already there, it seems to be a
natural choice.