Google Summer of Code

[Jonathan M Davis]

On Monday 07 March 2011 02:03:15 Regan Heath wrote:
> On Sat, 05 Mar 2011 21:40:47 -0000, Jonathan M Davis <jmdavisProg at gmx.com>
> 
> wrote:
> > So, for the current release, it's not a good idea to use -D when
> > compiling
> > actual code (and if you ever use version(D_Ddoc) yourself, it won't be a
> > good
> > idea ever), but that will be fixed by the next release. In the meantime,
> > you can
> > just skip using -D except when you're specifically generating
> > documentation.
> 
> So.. assuming I'm using visual studio and visual D and want documentation
> I need to add a post-build step, or custom build action on all my source
> files to execute dmd -D on them?  one at a time?

I don't know what the deal with visual D is. However, in addition to building 
documentation, -D enables version(D_Ddoc), and like any other version statement, 
that can totally change what code is created. In a number of cases, versioning 
documentation with a declared but undefined function (so no body) is necessary 
(for instance, if it's only one OS). Various Phobos developers quite correctly 
used version(D_Ddoc) for this (that's what it's for). However, this means that 
you _cannot_ use -D for a normal build, because in any case that version(D_Ddoc) 
was used, there's a high chance that it will result in unlinkable code. So, you 
have to build your documentation as a separate build.

Andrei decided that it was not reasonable to require that -D _have_ to be done 
in a separate build for your average program, so druntime and Phobos will be 
switching to using version(StdDoc) to version the documentation (using -
version=StdDoc as part of the build target which builds the docs for the std 
libs), and that will be in by the next release. However, in the interim (and 
permanently for any code which uses version(D_Ddoc)), you'll likely need to do -
D in a separate build if you want your code to work correctly.

How that relates to visual D, I have no idea. I've never used it.

- Jonathan M Davis