http://d.puremagic.com/issues/show_bug.cgi?id=511

           Summary: Various problems in the documentation
           Product: D
           Version: 0.174
          Platform: PC
        OS/Version: Windows
            Status: NEW
          Keywords: spec
          Severity: normal
          Priority: P4
         Component: www.digitalmars.com
        AssignedTo: bugzilla@digitalmars.com
        ReportedBy: deewiant@gmail.com
 BugsThisDependsOn: 508,509,510


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.


-- 

http://d.puremagic.com/issues/show_bug.cgi?id=511





------- Comment #1 from deewiant@gmail.com  2006-11-15 05:43 -------
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.


-- 

http://d.puremagic.com/issues/show_bug.cgi?id=511





------- Comment #2 from deewiant@gmail.com  2006-11-15 07:59 -------
Created an attachment (id=44)
 --> (http://d.puremagic.com/issues/attachment.cgi?id=44&action=view)
Listing for http://www.digitalmars.com/d/abi.html


-- 

http://d.puremagic.com/issues/show_bug.cgi?id=511





------- Comment #3 from deewiant@gmail.com  2006-11-15 08:00 -------
Created an attachment (id=45)
 --> (http://d.puremagic.com/issues/attachment.cgi?id=45&action=view)
Listing for http://www.digitalmars.com/d/arrays.html


-- 

http://d.puremagic.com/issues/show_bug.cgi?id=511





------- Comment #4 from deewiant@gmail.com  2006-11-15 08:00 -------
Created an attachment (id=46)
 --> (http://d.puremagic.com/issues/attachment.cgi?id=46&action=view)
Listing for http://www.digitalmars.com/d/attribute.html


-- 

http://d.puremagic.com/issues/show_bug.cgi?id=511





------- Comment #5 from deewiant@gmail.com  2006-11-15 08:00 -------
Created an attachment (id=47)
 --> (http://d.puremagic.com/issues/attachment.cgi?id=47&action=view)
Listing for http://www.digitalmars.com/d/class.html


-- 

http://d.puremagic.com/issues/show_bug.cgi?id=511





------- Comment #6 from deewiant@gmail.com  2006-11-15 08:02 -------
Created an attachment (id=49)
 --> (http://d.puremagic.com/issues/attachment.cgi?id=49&action=view)
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.


-- 

http://d.puremagic.com/issues/show_bug.cgi?id=511


smjg@iname.com changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |smjg@iname.com




------- Comment #7 from smjg@iname.com  2006-11-16 19:23 -------
*** Bug 181 has been marked as a duplicate of this bug. ***


-- 

http://d.puremagic.com/issues/show_bug.cgi?id=511


deewiant@gmail.com changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
  Attachment #49 is|0                           |1
           obsolete|                            |




------- Comment #8 from deewiant@gmail.com  2006-11-18 05:49 -------
Created an attachment (id=51)
 --> (http://d.puremagic.com/issues/attachment.cgi?id=51&action=view)
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


-- 

http://d.puremagic.com/issues/show_bug.cgi?id=511





------- Comment #9 from deewiant@gmail.com  2006-11-18 06:41 -------
Created an attachment (id=52)
 --> (http://d.puremagic.com/issues/attachment.cgi?id=52&action=view)
Listing for www.digitalmars.com/d/cppstrings.html


--