The text describing Sections in Documentation Generator page
(http://dlang.org/ddoc.html) needs improvement.
It reads:
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.
My issues with this are the following.
1. A section is not a name. It ~has~ a name (except when it
doesn't).
I propose the following change:
"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"
Of course the bracketed parts need to be cleared up, it's of
little use as I wrote it above.
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)?
