On Thursday, 1 February 2018 at 01:23:38 UTC, Adam D. Ruppe wrote:
Now, if a 5-character insertion requires 29 edit operations,
what do you think the programmer is going to do? Keep up with
it, or let the documentation stay slightly suboptimal and
out-of-date because it is a hassle?
To be fair, I feel with you and all the tables I have created are
formatted as good as DDoc allows, e.g.
https://github.com/dlang/phobos/blob/master/std/exception.d
Actually I prefer doing tables in Ddoc because it's a little
easier (if you know all the macros)
BTW, I also hate any syntax that requires editing every line.
Again, it goes back to that linear vs constant time edit. I
just copy/pasted that from the website. Using bbcode or html or
ddoc or adrdox, you just surround it with some tag like I did
there. Even indenting it is not really necessary to make it
legible and functional (though like every editor makes that
simple anyway).
I prefer markdown's ``` blocks to the leading for spaces
primarily for this reason, though adding language tags is a
secondary benefit to that.
This is also why I friggen hate comments with leading stars:
/*
* why write all
* this leading crap?
*/
/*
This is so much better
*/
Same here.
We recently added this to the DStyle:
https://dlang.org/dstyle.html#phobos_documentation
https://github.com/dlang/dlang.org/pull/2129
So, new Phobos code will be written without stars.
Edit those without using editor macros. Barf. And if you are
willing to use editor macros, the other justification for it -
making the comment look different than code - disappears since
if your editor is fancy enough to understand that leading *
crap and automatically reformat it, it could just as well
syntax highlight it in some way (including displaying leading
stars without saving them to the file!)
I wouldn't expect `...` to produce a link; it should just be
formatted differently (typically in monospace font) to
indicate that it's a code snippet.
It tells quite a bit about the complexity of Ddoc that I had to
add support for -D to run.dlang.io ...
Using [...] syntax for links makes more sense to me, even
though personally, I really prefer to just write plain ole
text and paste the URL in its own indented block:
http://example.nowhere.edu/blah/blah/blah
adrdox recognizes urls and I like writing them like that when I
actually write a url.... but the benefit of [reference] is that
it doesn't require an actual url. It is just a symbol, in scope
even.
I'm not a fan of Ddoc by any means, but that has been fixed in
Ddoc does this too now: https://run.dlang.io/is/75Z55o
https://github.com/dlang/dmd/pull/7043
