[dmd-beta] 64 bit beta for Linux
Jonathan M Davis
jmdavisProg at gmx.com
Sun Feb 6 18:01:34 PST 2011
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
More information about the dmd-beta