Cross referencing in Ddoc

[Walter Bright]

On 12/30/2013 12:14 PM, Jacob Carlborg wrote:
> On 2013-12-30 20:08, Walter Bright wrote:
>
>> This will create many unwanted links, in three scenarios:
>
> I don't think so, see below.
>
>> 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.
>
> The compiler knows which symbol it currently generating documentation for, just
> exclude that.

That's true.


>> 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.


>> 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.


> It's far better than having to add
> macros everywhere instead.

I'll have to disagree on that. I just finished doing it with std.datetime, and 
it didn't take more than a few minutes with global query-search-replace.