www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Let's kill the ddoc _name feature.

reply Adam D. Ruppe <destructionator gmail.com> writes:
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.
Mar 05
next sibling parent reply "Nick Sabalausky (Abscissa)" <SeeWebsiteToContactMe semitwist.com> writes:
On 03/05/2017 10:58 PM, Adam D. Ruppe wrote:
 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?
[...excellently stated argument snipped...]
 I propose that we kill it [...]
 what say yall?
I'm tempted to raise a pitchfork and unleash a bloodcurdling "kill it with fire!!!", but honestly, I actually don't especially care whether ddoc fixes this or not. And why don't I care? For one reason and one reason only: If it's fixed, then great, but if not...well, there's enough I dislike about ddoc anyway that I've already resigned to the idea that a few years from now, I very well may not be using it anyway, but rather some replacement (quite possibly yours, now that I've actually taken a look and find it to be very similar to what I had already started planning out in my head). If people want ddoc to be really good and widely used, then yes, "hear hear". But in all honestly, I'd rather just switch to something else or even write my own than try to change minds on ddoc (or ddox) matters.
Mar 05
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Monday, 6 March 2017 at 04:32:45 UTC, Nick Sabalausky 
(Abscissa) wrote:
 And why don't I care?
Oh, I agree. tbh my agenda here is more to reduce the merge conflict burden on my fork than to actually improve ddoc. I get sick of `git pull upstream master` eating an extra 5 minutes because HEAD shows the sane `gets a range` while master shows the `gets a _range`. So I want to get that upstreamed to lessen my work, and I'm offering a way that benefits them too so it becomes a win/win proposition.
Mar 05
prev sibling next sibling parent reply Jonathan M Davis via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Monday, March 06, 2017 03:58:11 Adam D. Ruppe via Digitalmars-d wrote:
 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?
 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?
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. I'd much rather have it never highlighted and then have to add the macros to do it manually. Right now, without actually looking at the resulting documentation, I'm never sure whether certain things are going to be highlighted or not. I expect that if I spent more time trying to get documentation just right, I'd be much more familiar with how it really works, but as it stands, 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. - Jonathan M Davis
Mar 05
parent Adam D. Ruppe <destructionator gmail.com> writes:
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.
Mar 06
prev sibling parent XavierAP <n3minis-git yahoo.es> writes:
On Monday, 6 March 2017 at 03:58:11 UTC, Adam D. Ruppe wrote:
 I propose that we kill it in a three step process:
+1 yes please
Mar 11