Up to date documentation..?

[Jonathan M Davis]

> On 10.04.2011 21:31, Jesse Phillips wrote:
> > On Sun, 10 Apr 2011 21:04:04 +0200, simendsjo wrote:
> >> Seems the documentation is lagging a bit behind.. It will be frustrating
> >> to rely on features that will be removed / vastly changed in the future.
> >> 
> >> Not quite sure I can trust the wiki..
> >> http://www.prowiki.org/wiki4d/wiki.cgi?LanguageDevel
> >> 
> >> This is under "pending decision", but it's marked with a specific
> >> version. * [DMD 2.051] toString() needs to be improved (Eg, change
> >> signature to void toString(void delegate(const char[] s) put, const
> >> char[] formatstr))
> >> 
> >> The changelog doesn't mention anything though.
> >> 
> >> Is my best bet to buy Andrei's book and learn from there? Not touching
> >> any features he doesn't mention?
> > 
> > Well TDPL does have errors in itself. So while the Wiki may be wrong, it
> > will at least give you the items that are changes and might be changing.
> > 
> > I'm unsure why Don tagged that line, but I think the idea was approved
> > and maybe it just didn't making in.
> 
> I've stumbled upon several documentation and implementation issues
> already. Guess tdpl also uses half-implemented features.
> 
> But the documentation at digitalmars together with that wiki page should
> give enough info deprecated and unimplemented features?

Maybe, but I doubt it. The information on features that are intended to be 
deprecated and those not fully implemented is generally sparse. For instance, 
does anywhere in the online docs or wiki mention that scoped classes are going 
away? It might, but I doubt it. The documentation is generally fairly good, 
but it's not necessarily going to be up-to-date with regards to recent or 
likely changes. The developers - Walter included - are generally more 
concerned with implementing changes and fixing bugs than updating 
documentation. Fortunately, the language spec is fairly stable now, so there 
aren't many changes, and most that do happen aren't large, but changes are 
still happening. TDPL was supposed to be released after everything was 
finalized, but it couldn't be delayed any further, and it was published before 
everything in it was fully implemented. It is _mostly_ correct however. The 
errata can be found here: 
http://erdani.com/tdpl/errata/index.php?title=Main_Page

As for the toString issue, there's a DIP for it: 
http://www.prowiki.org/wiki4d/wiki.cgi?LanguageDevel/DIPs/DIP9

As far as I know, it hasn't gone anywhere yet though. There's enough interest 
in it that I would expect it to happen at some point, but I don't know what 
it'll take for it to happen.

- Jonathan M Davis