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.
