Documentation for any* dub package, any version

[Jonathan M Davis]

On Monday, February 26, 2018 17:53:23 H. S. Teoh via Digitalmars-d-announce 
wrote:
> On Mon, Feb 26, 2018 at 06:43:55PM -0700, Jonathan M Davis via
> Digitalmars-d-announce wrote: [...]
>
> > 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.
>
> [...]
>
> It's a sorry state of affairs.  I dream of the day when I can just write
> code and documentation as-is, and downstream users can just use whatever
> doc formatting system they like and it will all Just Work(tm).
>
> Basically, it requires a standard way of writing documentation that
> every backend tool understands and supports, be it ddoc or adrdox or
> whatever else you fancy.  But I'm not holding my breath for that to
> materialize.

Basically, it requires that you do _nothing_ by hand - so no ddoc macros -
and the tools figure it all out from the json output from the compiler. As
soon as you start marking up the documentation in any way, unless it's a way
that _all_ of the tools understand, it's not going to work. And doing
something like using macros to generate links like Phobos or dxml do is
instant death to that - the same goes with adrdox's markup for links, though
that is more automated, so it would be possible to make that understood by
more tools, whereas links for ddoc macros are too specific for that.

ddoc does a good job of doing some of the basics, and it provides a way to
have really nice documentation if you go the extra mile (including using
additional tools to generate stuff like navigation bars to navigate between
modules), but it utterly fails as a way to just generate really nice
documentation. For that, it would have to process the entire project at once
and not be file-centric like it is now. It would also have to do more for
you and leave less to macros.

Ultimately, I think that it's going to be up to each project to choose which
tool or combination of tools to use to generate their documentation, and any
time that anyone doesn't bother to figure that out, you're going to get a
subpar result - though ddox and adrdox will likely result in better
documentation with no effort than pure ddoc will, since they do stuff like
generate the navigation bar for you.

Once I've cleaned it up and documented it, I'm actually planning on
releasing what I did for dxml as project on github so that it will be
possible for anyone's project to easily have documentation like dxml does
(including the navigation bar), though like Phobos, it requires manually
using linking macros, since it's just ddoc with a helper program to generate
the pieces that you can't do with macros. If you want documentation without
any attempt to mark anything up, ddox is probably your best bet.

- Jonathan M Davis