Cross referencing in Ddoc

[Walter Bright]

On 12/30/2013 3:13 PM, Sönke Ludwig wrote:
> 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).

Ddoc is very heavily used. I don't believe we can make such silent, breaking 
changes.


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

I don't see any particular advantage to using (name) rather than $(REF name), 
and some serious disadvantages with false positives like func(param). Oops! A 
markup language should really strive to minimize special syntax. (I'm often 
tripped up by false positives in the wacky markup languages in Skype, Github, 
Reddit, etc., each of which feels compelled to reinvent markup.)


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

My bias is towards being extremely conservative in adding new features to Ddoc, 
instead we should strive to get the max out of the existing system, and even 
rely on external post processors.