[Issue 511] New: Various problems in the documentation

[d-bugmail at puremagic.com]

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 at digitalmars.com
        ReportedBy: deewiant at 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.


--