[dmd-beta] 64 bit beta for Linux

[Jonathan M Davis]

On Sunday 06 February 2011 17:44:31 Jason House wrote:
> On Feb 6, 2011, at 6:58 PM, Jonathan M Davis <jmdavisProg at gmx.com> wrote:
> > You really shouldn't be compiling with ddoc enabled unless you're
> > building the documentation. There are just too many cases where you need
> > separate declarations for ddoc - often because of differences between
> > OSes. There are cases where the ddoc version is different _on purpose_.
> > In the case of std.file.DirEntry.isDir, it's const on Windows because it
> > can be. But because it can't be on Linux, the ddoc version doesn't list
> > it that way. Now, maybe it's on negligble benefit to have isDir const on
> > Windows given that it can't be on Linux, but there are definitely cases
> > where ddoc is forced to be different from a particular OS' version of a
> > declaration, simply because that declaration is different on different
> > systems.
> > 
> > Do _not_ expect your code to work if you compile with ddoc enabled.
> 
> Such requirements feel like a failure of design. Are there any lessons
> learned from these kinds of problems? I'm sure Walter did not intend
> separate ddoc versions.

Then why does version(D_Ddoc) even exist? It's _built in_. And honestly, I don't 
know how else you could do it. In cases such as when a function only exists on 
one OS, you _must_ use version(D_Ddoc) if you want it to show up on the 
documentation when generating it on other OSes. I don't know how it could be 
designed otherwise without doing something drastically different with ddoc.

Granted, the situation is not entirely ideal, but I don't see any way around it 
without just plain doing ddoc differently. Fortunately, the need for 
version(D_Ddoc) blocks is relatively rare, but it definitely happens. And it 
wouldn't surprise me at all if it happens _more_ in Phobos as Phobos' 
documentation is fixed so that it builds on _all_ platforms instead of just 
Windows as it has in the past. So, Phobos at minimum has this problem and can't 
get around it. A properly documented druntime would be rife with the problem.

It's quite possible (even likely) that most D projects won't have the problem, 
because they won't be writing functions which are OS-specific, and they won't be 
trying to massage their documentation to look better in version(D_Ddoc) blocks, 
but there _will_ be projects with the problem. druntime (assuming that it was 
properly documented - which it isn't) and Phobos definitely have the problem.

So, yes, perhaps it's a design flaw in ddoc. But I don't know how it would be 
fixed. On the whole, it works quite well, and while it's not exactly great that 
building with -D doesn't necessarily generate valid code and so you need two 
separate builds for  the code and the documenation, I don't think that it's all 
that big a deal. D builds quickly, and other documentation systems such as 
doxygen already have to be done as separate builds. The fact that ddoc is built 
into the compiler is a big boon, even if you really should be running the ddoc 
build as a separate build.

- Jonathan M Davis