digitalmars.D - [dox] Text describing Sections in Documentation Generator page needs
- Andre Artus (20/30) Aug 16 2013 The text describing Sections in Documentation Generator page
- H. S. Teoh (14/38) Aug 23 2013 Sorry for the late reply, it's kinda hard keeping up with this
- Andre Artus (20/63) Aug 24 2013 I think the description/explanation of a section name should be
- Andre Artus (19/19) Aug 24 2013 I have been racking my brain to find a suitable replacement for
The text describing Sections in Documentation Generator page (http://dlang.org/ddoc.html) needs improvement. It reads:SectionsThe 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
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: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 ':'. [...]SectionsThe 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).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
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: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).The text describing Sections in Documentation Generator page (http://dlang.org/ddoc.html) needs improvement. It reads: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 ':'.SectionsThe 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).[...]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
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, /** */ ][|"-- which seems questionable to me. I think we should tighten up the rules regarding section labels.
Aug 24 2013