Let's kill the ddoc _name feature.

[Adam D. Ruppe via Digitalmars-d]

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.