Bug 511 – Various problems in the documentation

Status
RESOLVED
Resolution
FIXED
Severity
normal
Priority
P4
Component
dlang.org
Product
D
Version
D1 (retired)
Platform
x86
OS
Windows
Creation time
2006-11-15T05:30:00Z
Last change time
2014-02-15T13:28:46Z
Keywords
patch, spec
Assigned to
bugzilla
Creator
matti.niemenmaa+dbugzilla
Depends on
467, 508, 509, 510, 512, 515, 516, 520, 550, 551, 556, 559, 560, 562, 563, 565, 566, 567, 576, 577, 610, 630, 631, 632, 633

Attachments

IDFilenameSummaryContent-TypeSize
44abi.txtListing for http://www.digitalmars.com/d/abi.htmltext/plain198
45arrays.txtListing for http://www.digitalmars.com/d/arrays.htmltext/plain2186
46attribute.txtListing for http://www.digitalmars.com/d/attribute.htmltext/plain158
47class.txtListing for http://www.digitalmars.com/d/class.htmltext/plain1838
49wc.patchPatch for word count at http://www.digitalmars.com/d/arrays.htmltext/plain3209
51wc.patchCorrected patch for word count at http://www.digitalmars.com/d/arrays.htmltext/plain3226
52cppstrings.txtListing for http://www.digitalmars.com/d/cppstrings.htmltext/plain270
53cpptod.txtListing for http://www.digitalmars.com/d/cpptod.htmltext/plain866
54ctod.txtListing for http://www.digitalmars.com/d/ctod.htmltext/plain2902
55dbc.txtListing for http://www.digitalmars.com/d/dbc.htmltext/plain1367
56dcompiler.txtListing for http://www.digitalmars.com/d/dcompiler.htmltext/plain419
57ddoc.txtListing for http://www.digitalmars.com/d/ddoc.htmltext/plain329
58declaration.txtListing for http://www.digitalmars.com/d/declaration.htmltext/plain277
59dlinks.txtListing for http://www.digitalmars.com/d/dlinks.htmltext/plain1806
60dll.txtListing for http://www.digitalmars.com/d/dll.htmltext/plain98
61enum.txtListing for http://www.digitalmars.com/d/enum.htmltext/plain72
62errors.txtListing for http://www.digitalmars.com/d/errors.htmltext/plain425
63exception-safe.txtListing for http://www.digitalmars.com/d/exception-safe.htmltext/plain808
64expression.txtListing for http://www.digitalmars.com/d/expression.htmltext/plain1149
65faq.txtListing for http://www.digitalmars.com/d/faq.htmltext/plain2362
66float.txtListing for http://www.digitalmars.com/d/float.htmltext/plain831
67function.txtListing for http://www.digitalmars.com/d/function.htmltext/plain2361
68future.txtListing for http://www.digitalmars.com/d/future.htmltext/plain490
69garbage.txtListing for http://www.digitalmars.com/d/garbage.htmltext/plain81
70htomodule.txtListing for http://www.digitalmars.com/d/htomodule.htmltext/plain304
71interfacetoc.txtListing for http://www.digitalmars.com/d/interfaceToC.htmltext/plain273
72memory.txtListing for http://www.digitalmars.com/d/memory.htmltext/plain154
73operatoroverloading.txtListing for http://www.digitalmars.com/d/operatoroverloading.htmltext/plain475
74statement.txtListing for http://www.digitalmars.com/d/statement.htmltext/plain904
75template.txtListing for http://www.digitalmars.com/d/template.htmltext/plain734
76templates-revisited.txtListing for http://www.digitalmars.com/d/templates-revisited.htmltext/plain270
77type.txtListing for http://www.digitalmars.com/d/type.htmltext/plain76
78warnings.txtListing for http://www.digitalmars.com/d/warnings.htmltext/plain144

Comments

Comment #0 by matti.niemenmaa+dbugzilla — 2006-11-15T05:30:13Z
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.
Comment #1 by matti.niemenmaa+dbugzilla — 2006-11-15T05:43:28Z
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.
Comment #2 by matti.niemenmaa+dbugzilla — 2006-11-15T07:59:14Z
Created attachment 44 Listing for http://www.digitalmars.com/d/abi.html
Comment #3 by matti.niemenmaa+dbugzilla — 2006-11-15T08:00:08Z
Created attachment 45 Listing for http://www.digitalmars.com/d/arrays.html
Comment #4 by matti.niemenmaa+dbugzilla — 2006-11-15T08:00:30Z
Created attachment 46 Listing for http://www.digitalmars.com/d/attribute.html
Comment #5 by matti.niemenmaa+dbugzilla — 2006-11-15T08:00:53Z
Created attachment 47 Listing for http://www.digitalmars.com/d/class.html
Comment #6 by matti.niemenmaa+dbugzilla — 2006-11-15T08:02:28Z
Created attachment 49 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.
Comment #7 by smjg — 2006-11-16T19:23:39Z
*** Bug 181 has been marked as a duplicate of this bug. ***
Comment #8 by matti.niemenmaa+dbugzilla — 2006-11-18T05:49:03Z
Created attachment 51 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
Comment #9 by matti.niemenmaa+dbugzilla — 2006-11-18T06:41:11Z
Created attachment 52 Listing for http://www.digitalmars.com/d/cppstrings.html
Comment #10 by matti.niemenmaa+dbugzilla — 2006-11-18T06:41:38Z
Created attachment 53 Listing for http://www.digitalmars.com/d/cpptod.html
Comment #11 by matti.niemenmaa+dbugzilla — 2006-11-18T06:41:55Z
Created attachment 54 Listing for http://www.digitalmars.com/d/ctod.html
Comment #12 by matti.niemenmaa+dbugzilla — 2006-11-18T06:42:08Z
Created attachment 55 Listing for http://www.digitalmars.com/d/dbc.html
Comment #13 by matti.niemenmaa+dbugzilla — 2006-11-18T06:42:20Z
Created attachment 56 Listing for http://www.digitalmars.com/d/dcompiler.html
Comment #14 by matti.niemenmaa+dbugzilla — 2006-11-18T06:42:34Z
Created attachment 57 Listing for http://www.digitalmars.com/d/ddoc.html
Comment #15 by matti.niemenmaa+dbugzilla — 2006-11-18T06:42:50Z
Created attachment 58 Listing for http://www.digitalmars.com/d/declaration.html
Comment #16 by matti.niemenmaa+dbugzilla — 2006-11-18T06:43:03Z
Created attachment 59 Listing for http://www.digitalmars.com/d/dlinks.html
Comment #17 by matti.niemenmaa+dbugzilla — 2006-11-18T06:43:17Z
Created attachment 60 Listing for http://www.digitalmars.com/d/dll.html
Comment #18 by matti.niemenmaa+dbugzilla — 2006-11-18T06:43:31Z
Created attachment 61 Listing for http://www.digitalmars.com/d/enum.html
Comment #19 by matti.niemenmaa+dbugzilla — 2006-11-18T06:44:19Z
Created attachment 62 Listing for http://www.digitalmars.com/d/errors.html
Comment #20 by matti.niemenmaa+dbugzilla — 2006-11-18T06:44:34Z
Created attachment 63 Listing for http://www.digitalmars.com/d/exception-safe.html
Comment #21 by smjg — 2006-11-18T07:04:23Z
(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.
Comment #22 by matti.niemenmaa+dbugzilla — 2006-11-18T07:08:29Z
Created attachment 64 Listing for http://www.digitalmars.com/d/expression.html
Comment #23 by smjg — 2006-11-18T07:09:52Z
(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); }
Comment #24 by smjg — 2006-11-18T07:12:04Z
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.
Comment #25 by matti.niemenmaa+dbugzilla — 2006-11-18T07:15:53Z
(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.
Comment #26 by matti.niemenmaa+dbugzilla — 2006-11-18T07:37:37Z
Created attachment 65 Listing for http://www.digitalmars.com/d/faq.html
Comment #27 by matti.niemenmaa+dbugzilla — 2006-11-18T09:11:32Z
Created attachment 66 Listing for http://www.digitalmars.com/d/float.html
Comment #28 by matti.niemenmaa+dbugzilla — 2006-11-18T10:07:56Z
Created attachment 67 Listing for http://www.digitalmars.com/d/function.html
Comment #29 by matti.niemenmaa+dbugzilla — 2006-11-18T10:12:50Z
Created attachment 68 Listing for http://www.digitalmars.com/d/future.html
Comment #30 by matti.niemenmaa+dbugzilla — 2006-11-18T10:16:02Z
Created attachment 69 Listing for http://www.digitalmars.com/d/garbage.html
Comment #31 by matti.niemenmaa+dbugzilla — 2006-11-18T10:30:38Z
Created attachment 70 Listing for http://www.digitalmars.com/d/htomodule.html
Comment #32 by matti.niemenmaa+dbugzilla — 2006-11-18T10:45:52Z
Created attachment 71 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.
Comment #33 by matti.niemenmaa+dbugzilla — 2006-11-18T13:19:49Z
(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.
Comment #34 by matti.niemenmaa+dbugzilla — 2006-11-18T13:20:18Z
Created attachment 72 Listing for http://www.digitalmars.com/d/memory.html
Comment #35 by matti.niemenmaa+dbugzilla — 2006-11-18T13:20:37Z
Comment #36 by matti.niemenmaa+dbugzilla — 2006-11-18T13:20:54Z
Created attachment 74 Listing for http://www.digitalmars.com/d/statement.html
Comment #37 by matti.niemenmaa+dbugzilla — 2006-11-18T13:21:19Z
Created attachment 75 Listing for http://www.digitalmars.com/d/template.html
Comment #38 by matti.niemenmaa+dbugzilla — 2006-11-18T13:21:43Z
Comment #39 by matti.niemenmaa+dbugzilla — 2006-11-18T13:21:59Z
Created attachment 77 Listing for http://www.digitalmars.com/d/type.html
Comment #40 by matti.niemenmaa+dbugzilla — 2006-11-18T13:24:04Z
Created attachment 78 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.
Comment #41 by matti.niemenmaa+dbugzilla — 2006-12-03T05:16:34Z
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.
Comment #42 by bruno.do.medeiros+deebugz — 2006-12-09T07:07:42Z
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);
Comment #43 by bugzilla — 2006-12-09T21:09:55Z
Fixed DMD 0.177