677 – [Tracker] Get the documentation cleaned up for 1.0

This tracker continues where issue 511 left off. With 1.0 around the corner, some serious work is still needed to get the language specification cleaned up.
If you find any issue with the D documentation that you feel should be fixed in time for 1.0, please make this issue depend on it. Holes, ambiguities, contradictions, undocumented features, typos, you name it.
If it's an instance in which compiler behaviour doesn't match the spec, but you think the compiler is doing what Walter intended and the spec just doesn't say it right, by all means add it. DDoc issues that are root causes of holes in the Phobos documentation may also be included.
This will help to prioritise issues surrounding the language spec, which must be fixed up before a compiler can be compliant. Then, as these spec problems are fixed, we will know for sure how any compiler problems related to these issues should be fixed.

Created attachment 98 [details] 
Proposed new file.d
In this file I include the output of the "diff -uN" of file.d against std/file.d

Comment on attachment 98 [details] 
Proposed new file.d
This is a corrected version of phobos' file implementation. Syntax has been corrected to conform to http://www.digitalmars.com/d/dstyle.html DDoc comments have been updated however are not complete yet. I'd like to know if these corrections are suitable or if I have touched things that shouldn't have been touched. I intend to check other files of Phobos, so feedback is appreciated.

This is a tracker issue. Patches or other contributions of code should not be attached here. Instead, they should have bug reports of their own.
To attach patches to a tracker makes it impossible to track whether they've been folded in.

Moreover, if you're going to include a diff, then including one that's as big as the code file or bigger is practically useless. There are two reasons for having diffs:
(a) to save disk space/bandwidth by storing/transmitting only the changes to a document rather than the whole updated document
(b) to draw the human reader's attention to which bits have actually changed
By changing the indentation style as well as fixing up the content, you have created a diff file that's bigger than either version of the code. What's more, we have a hard time finding the bits where you've actually changed the content among the mass of indentation fixes. Hence both benefits are lost.
On this basis, it would have made more sense to upload just your updated version of the page. You could, however, have gained benefit (b) by fixing the indentation first and then diffing between this intermediate version and that with your content fixes put in.

Comment on attachment 98 [details] 
Proposed new file.d
Due to time and feedback, marking this patch obsolete. If you think the changes are still useful, please resubmit the changes in a new bug report, not against this tracker bug.

That attachment already has a "new" bug report: bug 944.