| |
 | Posted by Jonathan M Davis
in reply to Satoshi |  Permalink Reply |
|
Jonathan M Davis 
Posted in reply to Satoshi
| 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
|
