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

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".

On Friday, 23 August 2013 at 21:41:01 UTC, H. S. Teoh wrote:
> Sorry for the late reply, it's kinda hard keeping up with this
> high-volume mailing list. :)

Tell me about it :)

> 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 ':'.

I think the description/explanation of a section name should be done separately from the description of sections. As far as I understand it there are only 2 section types that are sans name (summary and description), but bringing in names as part of the section description muddies the waters a bit (in my opinion).


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

> HST
> Yes.

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

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

A^2
It's kind of a section for text substitutions, each substitution pair can be seen as an parameter-less macro, but I think "Escapes=" still denotes a section, similar to the "Macros:" section.

I'm not quite clear on how "Escapes=", "Macros:", and embedded HTML serves the goal of decoupling the content from the presentation (e.g. PDF, LaTex,...). I would think that escape sequences would be configuration for the [output] generator.


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

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

A^2
If one wants to add a new named section (not predefined), do you need to create a macro expansion for it, or how does it work? It would probably be good to add some guidance for that.

I have been racking my brain to find a suitable replacement for the section description, I would appreciate your critique.

"A section is a block of text that is processed by the document generator. There are only two unlabeled sections, summary and description, all other sections are identified by a label (or name). A section label starts with the first non-blank character[1] on a line and continues until terminated by a colon (:).

Details of each kind of section follow"


1. This is technically not true, as the first non-blank character could be an asterisk. As far as  I can see the section labels follow the same rules as other identifiers. But, according to the description above the following,

/**
* 7^%$#@!  ][|:
*/

would be a valid section name/label --with the value "* 7^%$#@!  ][|"-- which seems questionable to me.

I think we should tighten up the rules regarding section labels.