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!)


Reply via email to