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.
