Documentation for any* dub package, any version

[Jonathan M Davis]

On Monday, February 26, 2018 19:51:27 Adam D. Ruppe via Digitalmars-d-
announce wrote:
> On Monday, 26 February 2018 at 15:49:19 UTC, Jonathan M Davis
>
> wrote:
> > Yeah. Any project that uses .ddoc files to define additional
> > macros isn't going to work properly
>
> It is actually more than that: I don't support user-defined ddoc
> macros at all. About 3/4 of the ones I've seen are just link
> macros.... instead of everyone creating their own random mix
> (like LREF, LREF2, REF, REF_ALTTEXT, PHOBOS_REF,
> PHOBOS_REF_ALTTEXT, OBJECT_REF...), I just have a built-in,
> simple, unified syntax: [symbol|alt text] where alt text is
> optional and symbol is looked up according to D scope rules. (you
> can also define custom symbols for things like author name links).
>
> I link to the source automatically too, including to the specific
> line of the correct overload for functions, so no need for macros
> to do those.
>
> Much easier to write in code: no more need to remember what this
> project decided to name its macro.
>
> (keep in mind that adrdox is explicitly NOT ddoc. I dropped a few
> ddoc misfeatures and modified some in a non-compatible way. I've
> given up on trying to save ddoc, it is rotten to the core.)

Well, then basically, projects are going to need to decide to go with adrdox
over ddoc if they want clean documentation. They'll probably get better
documentation with adrdox than the default ddoc if they do nothing, but any
project that actually goes to the effort of having nice looking
documentation is going to fall flat on its face with adrdox unless it buys
into adrdox whole hog.

dxml would be a prime example of a project that won't work with adrdox
though given that it tries to emulate what Phobos has done with its
documentation, and many of the macros are the same, which should minimize
how much the documentation will have to be mucked with if it ever ends up in
Phobos, but that means that it is very much not vanilla ddoc, let alone
adrdox.

- Jonathan M Davis