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

[Jonathan M Davis]

On Friday, January 21, 2011 19:33:24 Andrei Alexandrescu wrote:
> On 1/21/11 8:59 PM, Jonathan M Davis wrote:
> > 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.
> 
> Okay, sorry for snapping. As I guess it's easy to figure, it was out of
> passing frustration.
> 
> I'll remove the bodies now. (Wow, I feel like a mobster.)

LOL. I think that it's totally understandable that you weren't happy with the 
situation. I've never been able to figure out how to generate the docs in Linux 
(too bad at reading makefiles I guess - that and the impression from the 
documentation in Phobos itself gave me the impression that we weren't even 
trying to build the docs on Linux), and since you don't separate declarations 
and definitions in D, it never occurred to me that you could have functions with 
no bodies. So, apparently, I broke some stuff and didn't catch it. My apologies.

> > 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).
> 
> Yes, I think this is a good idea. But... yellow? :o)

I'm fine with a different color. Given that I didn't know how to generate the 
Phodos docs, I haven't even seen how that looks yet. Green and red both seemed 
wrong since green implies "go" or "good" whereas red is obviously for problems 
or warnings. So, I went with yellow. I'm not married to that color choice by any 
means. I just thought that it was a good idea to mark functions as Posix or 
Windows-only and put that note in a color other than black so that it would get 
noticed.

> Oh, one more thing. Try to use $(MACRO arg, arg) instead of
> HTML-specific tags. For example, to insert an anchor just say $(WEB
> foo.com, bar).

I think that I haven't been doing that because the URLs never actually appeared 
in the documentation when I did that. Perhaps it's different when generating with 
the Phobos makefiles though (even though I _was_ using the same .css and ddoc 
style files as Phobos...).

> Give me a few minutes and I'll checkin. Shoo, if you could look into the
> Windows issue, that would be great. Thanks!

I'll look over std.datetime (and std.file since I recently messed with that 
pretty thoroughly as far documentation goes) to make sure that the obvious stuff 
is fixed, though I'd assume that you fixed at least std.file, since that's where 
SHOO's problem was. I'm going to be redoing some of std.datetime's documentation 
soon anyway, since I think that I duplicated a bit too much across various 
template specializations, and I generally put ddoc comments on _every_ version 
of a function rather than just version(D_Ddoc). So, hopefully any unnecessary 
documentation in std.datetime should be removed soon (though I'd generally 
rather err on the side of over-documenting than under-documenting).

- Jonathan M Davis