Cross referencing in Ddoc

[Sönke Ludwig]

Am 30.12.2013 23:13, schrieb Walter Bright:
> On 12/30/2013 1:25 PM, Sönke Ludwig wrote:
>> Identifiers in documentation comments that are function parameters or
>> are names that are in scope at the associated declaration are emphasized
>> in the output.
>>
>> So the same problem is already reality - you already have to go through
>> the documentation to see if there are any mis-highlighted words.
> 
> 1. having a bad idea is not justification for doing it again :-)

Of course not, but my point was that the mistake has already been made,
so we may as well make the best out of it... not really doing it again
in that sense.

But if the decision is that in fact this was a mistake, it should get
removed and replaced by a proper solution sooner rather than later (it's
not that bad to lose some highlighting and Phobos uses $(D ...) anyway,
so just removing it wouldn't hurt much). And in that regard I'd like to
point to "D's goals for embedded documentation"
<http://dlang.org/ddoc.htm>. I very much agree with them, but the
current reality looks like the opposite - lots of macro-pseudo-HTML
markup, very difficult to read unprocessed in many places. So something
like using "#" or "()" to mark symbols + automatic cross referencing for
marked symbols would be a *really* nice to have.

> 
> 2. the requirement that the name be "in scope" does a pretty good job of
> reducing the problem. But cross references, are by definition CROSS
> references, i.e. they cross scopes. The whole point of them is they
> cross scopes, which means this becomes a much bigger issue.
> 

This is how I see it: single identifiers are only searched in the
current scope and in parent scopes of the same module. Cross references
to foreign scopes need to use qualified names (either ClassName.member
or pack.mod.Symbol). This avoids any inter-module issues and also a lot
of intra-module issues. Symbols in code blocks on the other hand can be
cross referenced completely automatically according to the usual D
lookup rules (including imports).