version(StdDoc)

[Jonathan M Davis]

On Friday, November 23, 2018 11:22:24 PM MST Neia Neutuladh via Digitalmars-
d-learn wrote:
> On Fri, 23 Nov 2018 21:43:01 -0700, Jonathan M Davis wrote:
> > 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.
>
> Keeping symbol names and function arguments consistent between them is
> also an issue; it's not just the documentation. The normal solution is to
> put the version blocks inside the relevant symbols -- sometimes type
> aliases inside version blocks and consistent code outside, sometimes
> functions where the entire body is a set of version blocks.

When you're versioning the implementation, it's trivial to just version the
function internals. Where version(D_Ddoc) becomes critical is with stuff
like structs or enums where the members actually differ across systems. And
while it's generally better to try to avoid such situations, there are
definitely situations where there isn't much choice. Fortunately, in the
vast majority of situations, versioning across systems isn't required at
all, and in most of the situations where it is, its only the implementation
that needs to differ, but that's not true in all cases.

I do wish though that it were legal to use version blocks in more situations
than is currently the case. For instance,

enum Foo
{
    a,
    b,
    version(linux) l,
    else version(Windows) w,
}

is not legal, nor is

enum Foo
{
    a,
    b,
    version(linux) c = 42,
    else version(Windows) c = 54,
}

You're forced to version the entire enum. Fortunately, structs and classes,
do not have that restriction, so having to version an entire struct or class
at once is usually only required when the type needs to be declared on some
systems but not others (as is the case with WindowsTimeZone), and such
situations are rare.

- Jonathan M Davis