Let's kill the ddoc _name feature.

[Adam D. Ruppe via Digitalmars-d]

Have you ever seen how _ddoc has a bunch of random names prefixed 
with underscores throughout the source? Or ever used _ddoc and 
found random words italicized?

Take a gander at this old file I generated with `dmd -D 
simpledisplay.d` a long time ago:

http://arsdnet.net/ddoc/simpledisplay.html

See in the "setClipboardText" function, near the top, how it says 
"copies some /text/ to the clipboard"? Why is that italic?

Or, under `struct Pen`, it says "the foreground _color_", 
underlined?

This is the old ddoc style, but the new style has the same thing:
http://arsdnet.net/dcode/simpledisplay.html#setClipboardText - 
text is still in a weird font there.


That's a ddoc "feature" that will highlight any occurrence in the 
text of a name that happens to be in scope. It is almost never 
what you actually want. In this example, it highlights "text" and 
"color" because they are the names of function parameters, but in 
the documentation, I was using the plain English words and did 
not desire emphasis.

Ddoc forces you to opt out of this by prefixing the words with an 
underscore. This is extremely common, since you almost never want 
ddoc's default behavior:

https://github.com/dlang/phobos/blob/master/std/range/interfaces.d#L8

"around _range objects "

https://github.com/dlang/phobos/blob/master/std/algorithm/mutation.d#L765

"$(REF_ALTTEXT input _range, isInputRange, std,_range,primitives)"

Yes, even in links, you have to escape common words.

https://github.com/dlang/phobos/blob/master/std/algorithm/mutation.d#L4

"generic _mutation algorithms"


https://github.com/dlang/phobos/blob/master/std/stdio.d#L826

"Calls $(HTTP 
cplusplus.com/reference/clibrary/cstdio/_fflush.html, _fflush)"



The leading underscore is common because the default behavior it 
escapes is extremely undesirable.


I propose that we kill it in a three step process:


1) Define the macros it implies to return $0, basically erasing 
themselves, in both the Phobos and the default dmd macro 
definitions. Then, if you don't write the leading underscore, the 
behavior is the same before and after.

2) Remove all occurrences of the leading underscore in Phobos and 
druntime. This can take as long as it takes, at least going 
forward we won't use it anymore.

3) Optionally, officially deprecate any detected uses of the old 
behavior, pending removal so `_front` is literally printed 
`_front` and `range` is plain `range` instead of `front` and 
`$(DDOC_PSYMBOL range)` (or whatever it is, it has I believe two 
macros depending on the context).


Step 3 is optional since having it doesn't really *hurt* once 
step one is complete, unless you hit some unlucky case where you 
actually want the underscore (such as maybe linking to some weird 
external resource, or discussing a mangled C name).

But I consider step one to be an absolute must, this "feature" 
has been a minor, but constant annoyance to most ddoc users I 
have talked to, and step two to be a REALLY nice thing to do.

what say yall?



BTW this was one of the first things I decided I'd kill with fire 
in dpldocs. I support detecting the underscore... just so I can 
warn me to fix it, and ignore it in generation. I have never seen 
any redeeming value to this ddocism.