[Issue 10769] New: Text describing Sections in Documentation Generator page inaccurate

[d-bugmail at puremagic.com]

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

           Summary: Text describing Sections in Documentation Generator
                    page inaccurate
           Product: D
           Version: unspecified
          Platform: All
        OS/Version: All
            Status: NEW
          Severity: minor
          Priority: P2
         Component: websites
        AssignedTo: nobody at puremagic.com
        ReportedBy: andre.artus at gmail.com


--- Comment #0 from Andre Artus <andre.artus at gmail.com> 2013-08-07 01:30:24 PDT ---
The text describing Sections in Documentation Generator page
(http://dlang.org/ddoc.html) is not accurate.

> Sections

> The document comment is a series of Sections. A Section is a name that is the first non-blank character > on a line immediately followed by a ':'. This name forms the section name. The section name is not case > sensitive.

1. A section is not a name. It has a name (except when it doesn't). May I
propose:
" A section is a block of text that is given special meaning by the document
generator based on either position or a{n} [predefined?]
(identifier|name|label|keyword). Details of each kind of section follow"

2. A name can be more than one character. I believe all the standard sections
have names longer than 1 character.

3. Some sections do not end their identifiers with a colon (':') to wit
"Escapes=".

4. The wording leaves the impression that arbitrary named sections are
possible, is this the case? Or are the named sections predefined (i.e. those
listed as standard and special sections)?

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------