On Monday, 6 March 2017 at 05:27:12 UTC, Jonathan M Davis wrote:
My big problem with how it currently works with ddoc is it
seems way too ad-hoc with regards to when something is
highlighted or not.
There's two rules: DDOC_PSYMBOL highlights any text that happens
to match the current declaration name, and DDOC_PARAM highlights
anything that matches any of the current parameters. Run dmd -D
over this:
---
/++ foo.baz are bar module
Macros:
DDOC_PSYMBOL=PSYMBOL-$0
DDOC_PARAM=PARAM-$0
+/
module foo.baz.bar;
/// foo and baz are bar outer
struct baz {
/// foo and baz are bar range and Range
void foo(Range)(int bar) {}
}
---
You'll get something like this:
foo.baz are PSYMBOL-bar module
baz
Declaration
struct PSYMBOL-baz;
foo and PSYMBOL-baz are bar outer
foo
Declaration
void PSYMBOL-foo(Range)(int PARAM-bar);
PSYMBOL-foo and baz are PARAM-bar range and Range
So you can see what's going on more clearly there: there's two
kinds of highlights for name and params. It applies in the
declaration ddoc outputs, AND in the comment text. The name also
includes the last part of the module name, so `std.range` forces
you to write `_range` in the module declaration comment.
But, as you could see from the real world example in my other
post, function parameters and names are often regular words that
appear in the text or in links.... and you almost never actually
want them highlighted. Hence the extremely frequent escaping.
The highlighting in the declaration is OK, we could keep that if
we are fine with just jumping to the compiler and ripping the
highlight out there (or doing a css hack such that the
highlighted things are displayed normally, but that'd still break
links that mention them so the compiler is the best realistic
option), but I don't think it is that useful anyway so defining
the macro out of existence gives us the easiest path forward.
I suspect that a lot of the documentation I write has stuff
highlighted when it shouldn't be or not highlighted when it
should be.
indeed.
