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.
