version(StdDoc)

[Jonathan M Davis]

On Friday, November 23, 2018 7:55:04 PM MST H. S. Teoh via Digitalmars-d-
learn wrote:
> Adam does have a very good point about showing all alternatives to docs,
> though.  Arguably, that's what ddoc *should* do.  If the programmer
> wrote a ddoc comment in the code, it probably should be processed as
> part of doc generation, regardless of whether that code sits in some
> deeply-nested version blocks that ends up not being compiled.  Binding
> ddoc generation to the compile process seems not such a good idea in
> retrospect.

Honestly, I would argue that if you have multiple versions of the
documentation, then there's a serious problem. The documentation shouldn't
be platform-dependent even if the symbols are. Even if the documentation
needs some extra notes for a specific platform, it should all be in one
documentation block that anyone using the symbol can read. Providing
different documentation for different platforms just leads to folks not
understanding how the symbol differs across platforms, leading to code that
is even more platform-dependent when it really should be as platform
independent as possible.

The only situation I can think of at the moment where anything along the
lines of combining documentation across platforms makes sense would be if
there is a nested symbol that exists on only one platform (e.g. a member
function of a struct or a member of an enum). In that case, one platform
would have the main documentation, and then system-specific symbols would be
documented in those version blocks - but only those symbols. A solution like
that might work reasonably well, but you still have the problem of what to
do when a symbol is documented in multiple version blocks, and having almost
all the documentation in one version block and a few pieces of it in other
version blocks would risk getting confusing and messy. As such, I'm not sure
that the fact that ddoc forces you to have a separate set of declarations
just for the documentation is really a bad thing. It puts all of the
documentation in one place.

The bigger problem IMHO is how -D affects the build. Both it and -unittest
have the fundamental problem that because they create their own version
identifiers, they really shouldn't be part of the normal build, and yet the
way that they're set up to be used, it's as if they're expected to be part
of the normal build - with -D just causing the compiler to generate the
documentation in addition to the binary, and -unittest making the unit tests
run before main rather than replacing main.

At this point, I really wish that at minimum, -D were not set up to be part
of the normal build process so that version(D_Ddoc) would not affect it. The
same with -unittest. Ideally, it really would have replaced main rather than
putting the unit tests before it, with it providing main if one wasn't
there. That still doesn't solve all of the problems when using
version(unittest), but I doubt that much of anyone really wants to be
running unit tests as part of their application, and having such flags
clearly designed to create special builds rather than being designed such
that they could be used with the normal build would have fixed certain
classes of problems.

As for the issue of versioning the documentation, I don't really see a clean
one. Having the documentation build affected by version and static if and
the like causes some problems, but having it ignore them would likely cause
other problems. Regardless, I suspect that having the version identifiers
and static ifs be ignored almost requires a separate tool from the compiler
(such as Adam's documentation generator or ddox), because it's pretty clear
that ddoc was set up to generate the documentation for symbols as the
compiler compiles them, whereas a tool that ignored version identifiers and
static ifs would be processing the file quite differently.

- Jonathan M Davis