Inline code in the docs - the correct way

[Adam D. Ruppe]

On Friday, 2 February 2018 at 18:45:50 UTC, H. S. Teoh wrote:
> In an ideal world, you wouldn't need to encode any of this 
> stuff inside a ddoc comment.

Well, that's what the Phobos REF macro does... sort of. You write 
$(REF symbolName, std, module) and the macro figures out the 
link. Though, even that macro is based on the url structure on 
dlang.org... it separates package arguments because it needs to 
$2_$3.html#$1 which doesn't match any generator. But it is a heck 
of a lot better than the old way of $(LINK2 std_string.html, 
std.string) which is just plain broken (and btw a few of those 
are still there :( ).

>  Since ddoc comments are processed by the compiler, and the 
> compiler has all of the information necessary to resolve 
> identifiers, arguably all that *should* be needed is just a way 
> to indicate in the docs, "this word is an identifier", and the 
> compiler would figure out what it's referring to, perhaps 
> expand it into a fully-qualified name like 
> std.range.primitives.isInputRange.

Right, this is exactly what adrdox does and it has been a 
smashing success to me. It'd be nice if ddoc did it too (at least 
so I don't have to deal with so many merge conflicts on the 
broken phobos source links!)