[dox] Text describing Sections in Documentation Generator page needs improvement

[H. S. Teoh]

Sorry for the late reply, it's kinda hard keeping up with this
high-volume mailing list. :)


On Sat, Aug 17, 2013 at 12:08:06AM +0200, Andre Artus wrote:
> 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).

Yeah, it should say that the document comment is divided into sections,
and section names consist of a sequence of non-blank characters followed
a ':'.


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

Yes.


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

Oh? I don't think that's a section, that looks like a macro definition.


> 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)?

Arbitrary names are possible. The predefined names may have special
interpretations.


T

-- 
Long, long ago, the ancient Chinese invented a device that lets them see through walls. It was called the "window".