511 – Various problems in the documentation

With the upcoming release of D 1.0, I decided to take it upon myself to go through the documentation and note any inconsistencies, typos, errors, etc.
I'll be posting a plaintext attachment for each page of the documentation as soon as I'm done with one, listing problems and possible solutions.
Where there's a complete contradiction with compiler behaviour and the spec, it'll be separately filed in the Bugzilla. This bug is marked as depending on those bugs.
I won't go through the formal parts of the spec (LinkageAttribute, ScopeStatement... *head explodes*) and I'll try to avoid skimming too much, instead attempting to actually read every sentence in order to ensure I catch every single typo.
Large missing sections aren't mentioned here: this is only for lots of small corrections. For instance, the fact that functions taking arrays can be called as properties of arrays is (still) not mentioned anywhere in the spec, but it won't be listed below. If the feature were used in an example but not explained, then it would be listed. This is essentially just because I can't remember every single feature of D and I'm just woefully unfamiliar with others (mostly template-related stuff), so I don't notice that something is missing, whereas it's easy to see that something is mentioned only partially or incorrectly.
All nontrivial example code will be tested in the latest version of DMD (0.174 at time of writing, and hopefully also at time of completion), and corrections will be noted to all of that, as well, below.
With thanks to the Doc Comments at the Wiki4D: http://www.prowiki.org/wiki4d/wiki.cgi?DocComments - after processing a page myself I'll check for anything I've missed there, and it's already proved helpful, though I've only completed two pages so far.
- Matti "Deewiant" Niemenmaa, 2006年11月15日
--
Format:
PROBLEMs are actual problems, e.g. non-compiling or incorrect example code, or blatantly incorrect or outdated information in the text or comments.
MISSINGs are situations where something that should be mentioned for clarification is not, leading to unclear documentation.
NITPICKs are minor, e.g. spelling mistakes in non-code sections or code comments I see as confusing.
Suggested SOLUTIONs provided where it isn't completely obvious from the problem description.

Well, it seems that attaching doesn't work at this time - Bugzilla throws internal errors in my face. I've emailed Brad about the issue. Until it's fixed, this bug is unfortunately fairly useless, but after that, I'll add the "patch" keyword and attach a bunch of files.

Created attachment 44 [details] 
Listing for http://www.digitalmars.com/d/abi.html 

Created attachment 45 [details] 
Listing for http://www.digitalmars.com/d/arrays.html 

Created attachment 46 [details] 
Listing for http://www.digitalmars.com/d/attribute.html 

Created attachment 47 [details] 
Listing for http://www.digitalmars.com/d/class.html 

Created attachment 49 [details] 
Patch for word count at http://www.digitalmars.com/d/arrays.html
This is all for now. I'll be back with more on the weekend.

*** Bug 181 has been marked as a duplicate of this bug. ***

Created attachment 51 [details] 
Corrected patch for word count at http://www.digitalmars.com/d/arrays.html
Made a major screwup in the original patch, corrected that now.
I realised this when I found the original version of the code at www.digitalmars.com/d/cppstrings.html.
Updated wc.patch attached. It applies to the original code at www.digitalmars.com/d/arrays.html, not the version created after applying the previous patch.
Changes in addition to those in the original:
	- foreach loop has an added "j" index, keeping the original "j"s as "j"s instead of turning them into "i"s
	- the output loop at the end of the program uses the sorted keys array to match the version at cppstrings.html

Created attachment 52 [details] 
Listing for http://www.digitalmars.com/d/cppstrings.html 

Created attachment 53 [details] 
Listing for http://www.digitalmars.com/d/cpptod.html 

Created attachment 54 [details] 
Listing for http://www.digitalmars.com/d/ctod.html 

Created attachment 55 [details] 
Listing for http://www.digitalmars.com/d/dbc.html 

Created attachment 56 [details] 
Listing for http://www.digitalmars.com/d/dcompiler.html 

Created attachment 57 [details] 
Listing for http://www.digitalmars.com/d/ddoc.html 

Created attachment 58 [details] 
Listing for http://www.digitalmars.com/d/declaration.html 

Created attachment 59 [details] 
Listing for http://www.digitalmars.com/d/dlinks.html 

Created attachment 60 [details] 
Listing for http://www.digitalmars.com/d/dll.html 

Created attachment 61 [details] 
Listing for http://www.digitalmars.com/d/enum.html 

Created attachment 62 [details] 
Listing for http://www.digitalmars.com/d/errors.html 

Created attachment 63 [details] 
Listing for http://www.digitalmars.com/d/exception-safe.html 

(In reply to comment #11)
> Created an attachment (id=54) [edit]
> Listing for www.digitalmars.com/d/ctod.html
`PROBLEM:
	Under "Formatted printing", the D code uses "import stdio;" which hasn't
	compiled for a very long time: use "import std.stdio".`
I don't think "import stdio;" has ever worked. The std package was established long before std.stdio was invented.
Moreover, it should be pointed out that printf shouldn't be mentioned at all under "The D way". To repeat the C way before giving the real D solution is inconsistent with the format of the rest of the page and the other conversion pages.

Created attachment 64 [details] 
Listing for http://www.digitalmars.com/d/expression.html 

(In reply to comment #12)
> Created an attachment (id=55) [edit]
> Listing for www.digitalmars.com/d/dbc.html
"SOLUTION:
	Replace long with float, double, or real, or use casts."
Using casts won't help the out contract to succeed. However, what will help is to change it to
 out (result)
 {
 assert(result * result <= x);
 assert((result + 1) * (result + 1) > x);
 }

The http:// has disappeared from your attachment descriptions. It is nice to be able to get to the pages of the spec straight from the comments here.

(In reply to comment #23)
> Using casts won't help the out contract to succeed.
You're right, my mistake: of course casting the result to a floating point type won't magically bring back what was lost in truncating to a long.(In reply to comment #24)
(In reply to comment #24)
> The http:// has disappeared from your attachment descriptions. It is nice to
> be able to get to the pages of the spec straight from the comments here.
> 
Fixed. That _was_ why I originally had it there, I just forgot about it today.

Created attachment 65 [details] 
Listing for http://www.digitalmars.com/d/faq.html 

Created attachment 66 [details] 
Listing for http://www.digitalmars.com/d/float.html 

Created attachment 67 [details] 
Listing for http://www.digitalmars.com/d/function.html 

Created attachment 68 [details] 
Listing for http://www.digitalmars.com/d/future.html 

Created attachment 69 [details] 
Listing for http://www.digitalmars.com/d/garbage.html 

Created attachment 70 [details] 
Listing for http://www.digitalmars.com/d/htomodule.html 

Created attachment 71 [details] 
Listing for http://www.digitalmars.com/d/interfaceToC.html
I skipped http://www.digitalmars.com/d/iasm.html since I don't know enough Assembly language to have any kind of reasonable opinion on the contents.

(In reply to comment #18)
> Created an attachment (id=61) [edit]
> Listing for www.digitalmars.com/d/enum.html
> 
Having come across property.html, I think it would be best to just link to that and say that enums are integral types. That, or add .sizeof, .alignof, and .mangleof to the list as well.

Created attachment 72 [details] 
Listing for http://www.digitalmars.com/d/memory.html 

Created attachment 73 [details] 
Listing for http://www.digitalmars.com/d/operatoroverloading.html 

Created attachment 74 [details] 
Listing for http://www.digitalmars.com/d/statement.html 

Created attachment 75 [details] 
Listing for http://www.digitalmars.com/d/template.html 

Created attachment 76 [details] 
Listing for http://www.digitalmars.com/d/templates-revisited.html 

Created attachment 77 [details] 
Listing for http://www.digitalmars.com/d/type.html 

Created attachment 78 [details] 
Listing for http://www.digitalmars.com/d/warnings.html
Phew! That's all folks.
I won't be going through the Phobos documentation, at least right now: it's quite a bit more work since there are quite a bit more holes. To go through it in any reasonable way would practically require writing a large part of it again.

Most changes folded in for DMD 0.176. The following issues, mostly of type NITPICK, remain (note that I didn't go through the pages thoroughly again, I just checked the changes I had already marked and their immediate vicinity):
http://www.digitalmars.com/d/class.html
	Under "Constructors", there is a code snippet "this() { if (a) ? this(1) : super(); }	// ok" which is syntactically invalid. Remove the "if".
http://www.digitalmars.com/d/ctod.html
	Under "Struct Initializations", there's an incorrect apostrophe in "{}'s".
	Under "Declaring struct types and variables", there's an excessive ampersand in the last sentence.
http://www.digitalmars.com/d/dbc.html
	Under "In, Out and Inheritance" only one of the "satisified" typos was corrected to "satisfied".
http://www.digitalmars.com/d/expression.html
	The last code block under "IsExpression" refers to x in a comment, while it should say v.
http://www.digitalmars.com/d/faq.html
	Under "Why are floating point values default initialized to NaN rather than 0?" the word "NaN's", with an incorrect apostrophe, is used instead of "NaNs".
http://www.digitalmars.com/d/operatoroverloading.html
	Under "Overloading == and !=" it is stated that that "if (a == null)" is converted to "if (a.opCmp(null)) which will fail if opCmp() is a virtual function". It should say opEquals instead of opCmp.
http://www.digitalmars.com/d/templates-revisited.html
	Under "SFINAE - Substitution Failure Is Not An Error" the last code snippet asserts when run: to fix it, change "typedef" to "alias", matching the change made to http://www.digitalmars.com/d/cpptod.html.

A Problem in http://www.digitalmars.com/d/function.html ,
in Lazy Variadic Functions, the following code segment is wrong:
 int delegate[] dg;
 foo(1, 3+x, dg, cast(int delegate[])null);
Should be:
 int delegate() dg;
 foo(1, 3+x, dg, cast(int delegate())null);

Fixed DMD 0.177