www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - [dox] Text describing Sections in Documentation Generator page needs

reply "Andre Artus" <andre.artus gmail.com> writes:
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)?
Aug 16 2013
next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
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".
Aug 23 2013
prev sibling next sibling parent "Andre Artus" <andre.artus gmail.com> writes:
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.
Aug 24 2013
prev sibling parent "Andre Artus" <andre.artus gmail.com> writes:
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.
Aug 24 2013