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.
