Adding Markdown to Ddoc

[Adam D. Ruppe]

On Tuesday, 12 December 2017 at 11:33:45 UTC, Jonathan M Davis 
wrote:
> Personally, I would _very_ much like to see the magic 
> formatting in ddoc kept to a minimum.

You know what drives me nuts? This* is weird.

* it is rendered as a list item! And I know, you can do \*. But 
ugh.

Ugh. Or why is _this_ italic?


But those, while enough to bring my hatred, are not why I did 
something new for adrdox... it is the missed opportunities for 
links. adrdox links are more inspired by the wikipedia link 
syntax and uses knowledge of D to keep them very concise:

/// Does something. See also: [bar].
void foo();

/// Does something similar. See also: [foo].
void bar();


When it sees a string in brackets, it does a name lookup 
following D's scoping rules for that declaration, and creates a 
link to it. It even understands imports (slightly buggy but i'll 
fix that eventually):

import std.stdio;
import arsd.color;

/// calls [writeln] on the given [Color|color].
void bar(Color s, string txt);



You also see the pipe syntax there which replaces the text for 
the link. It always does [link_to|displayed_text] where 
displayed_text = link_to if it is not present. In markdown, i 
often reverse these.


But anyway, I struggled a bit on using single brackets for this, 
since I hate magic syntax too... but I went with it because 
cross-linking like this is VERY common and adds a lot to the 
documentation. I use it very frequently (in the docs I've written 
with the new generator; many of mine are still in the transition 
period from ddoc). In fact, I use it almost as frequently as 
`code` (which doesn't attempt namespace lookups because it is too 
generic and linking in there leads to silly results).


Phobos' $(REF) macro tries to do something similar but it is a 
huge pain since it needs more qualification; it doesn't look 
stuff up in the actual D.

Cross linking in documentation I find is a huge win in legibility 
for the coder and readability for the end user. *this* vs $(B 
this)? meh whatever.