On Sunday 06 February 2011 17:44:31 Jason House wrote: > On Feb 6, 2011, at 6:58 PM, Jonathan M Davis <[email protected]> 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 _______________________________________________ dmd-beta mailing list [email protected] http://lists.puremagic.com/mailman/listinfo/dmd-beta
