[phobos] lots of spurious code that doesn't work

[Jonathan M Davis]

On Friday, January 21, 2011 18:42:16 Andrei Alexandrescu wrote:
> After having updated there are reams of code that doesn't work. There
> are a few issues that I think we need to be careful of:
> 
> * There are absolutely huge wads of code versioned under D_ddoc, that
> has rotten and prevents documentation generation. This means code was
> committed without compiling. Please compile all code with the relevant
> flags before committing.
> 
> * We already have version=ddoc in posix.mak for documentation. Is D_Ddoc
> predefined somewhere? In
> 
> * Walter and I have very different styles but generally are trying to
> make every line of Phobos count. I have no doubt examples can be found
> to the contrary, but please let's stop this trend of verboseness like:
> 
> @property string name() const
> {
>    assert(0, "No implementation. Function exists only for DDoc
> generation"); }
> 
> Just don't define the function! There are many examples. Whenever
> inserting a line of code, please ask yourself what amount of work that
> line does.
> 
> I'll try to fix things now.

Well, I know that I'm guilty of that line. I didn't know that you _could_ 
declare a function with no definition. I would have done that had I known that it 
was legal.

There does seem to be a tendency in Phobos to put ddoc comments on the Windows 
versions of functions if there are multiple versions, which means that building 
ddoc on posix isn't going to look anything like building it on Windows. I'd 
suggest that if a function has to be versioned for different OSes that either the 
versioning be done in the function body or that the function be put in 
version(D_Ddoc) with the documentation only on that version (though obviously 
without a body for the function, unlike what I've been doing).

And thanks for pointing out how to build the documentation on posix. I didn't 
know that you could. I'll certainly make sure to do that before checking 
anything in in the future.

- Jonathan M Davis