www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - Create doc simultaneously with compilation

reply Satoshi <satoshi rikarin.org> writes:
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.
Feb 19 2017
next sibling parent Jonathan M Davis via Digitalmars-d-learn writes:
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
Feb 20 2017
prev sibling parent kinke <noone nowhere.com> writes:
On Sunday, 19 February 2017 at 22:44:54 UTC, Satoshi 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.
That is an LDC bug which has been fixed as part of the 2.072.2 merge which is in current LDC master.
Feb 20 2017