adrdox vs markdown vs ddoc

[Seb]

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