Create doc simultaneously with compilation

[Jonathan M Davis via Digitalmars-d-learn]

On Sunday, February 19, 2017 22:44:54 Satoshi via Digitalmars-d-learn wrote:
> Why is not possible to create documentation, compile code and
> generate header files simultaneously?
>
> When I pass -D and -Dd flags to ldc2 command it won't create doc
> until I don't pass -o- flag too.

I don't know what the deal is with the header flags and ldc2, but I would
point out that in general, generating the documentation at the same time
that you're generating your actual executable or library is not necessarily
a good idea, because of the D_Ddoc version identifier. It's quite possible
(and sometimes necessary) for code to do something like

version(D_Ddoc) enum Foo
{
    ///
    a,

    ///
    b,

    ///
    c,
}
else version(Posix) enum Foo
{
    a = 19,
    b = 24,
}
else version(Windows) enum Foo
{
    a = 17,
    c = 47,
}
else
    static assert(0, "This platform is not supported");

And that could be done with single functions or entire classes. Fortunately,
most D code doesn't need to do that, but some does (particularly dealing
with stuff that is not the same across operating systems and can't be
abstracted away). And if you generate your documentation as part of your
regular build, then any code you depend on that had to use version(D_Ddoc)
anywhere will not work properly.

In order to reduce the risk of folks code breaking like this, Phobos uses
version(StdDdoc) instead of version(D_Ddoc) for its documentation build, and
if it didn't, then you would hit problems pretty quickly when generating
your documentation as part of your normal build, because it does have a
number of places where it's forced to have separate documentation so that it
can document what's on all systems, whereas what actually gets generated for
each system is not quite the same (e.g. std.file has to do it with some
stuff related to file times, and std.datetime has do to it with
WindowsTimeZone).

Because Phobos uses StdDdoc instead of the built-in D_Ddoc, the odds of you
hitting it are much less and depend primarily on what any 3rd party
libraries you're using do, but the D_Ddoc version identifier does exist, and
you run the risk of problems if you generate your documentation as part of
your normal build. So, do what you're going to do, but I think that it's
just asking for trouble if you generate your documentation with your normal
build.

- Jonathan M Davis