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.
