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 2017
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 2017
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 2017
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 2017
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 2017
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 2017