www.digitalmars.com         C & C++   DMDScript  

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

On Sun, Aug 25, 2013 at 04:27:18AM +0200, Andre Artus wrote:
 On Friday, 23 August 2013 at 21:41:01 UTC, H. S. Teoh wrote:

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

Actually, I believe the summary and description are regarded as the same section. The only reason they are referred to differently, is because conventionally, the first paragraph should just be a short 1-line summary of the symbol being documented. The description contains the more detailed discussion of the symbol. This is the only section without a name. All other sections begin with a name followed by a colon, and consist of any number of paragraphs / code examples, etc., up until the next section name. One gotcha here that should be mentioned in the docs, is that if the docs contain a paragraph that ends with ':' (say, it's referring to a code example immediately following), one should take care that it's not a single word on the line followed by the ':', otherwise ddoc will mistake it for the beginning of the next section, and interpret the word as the section name. [...]
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.

I would think the Escapes= definition should be put in a separate .ddoc file, not inside code comments. That's the other thing that sorely needs proper docs: a newcomer probably has no idea what conventions are used when dealing with ddoc. Usually macros are kept in one or more .ddoc files, and the -Dxxx options are used to include them when generating docs for the source code. While it *is* possible to include macro definitions in the source code itself, this is generally a bad idea for projects that have more than a single source file (and even then, it's arguable). You want to keep your macro definitions apart from the code so that you can substitute a different .ddoc file, say, when you want to target a different output format. How to target multiple output formats, etc., all need explaining, which the current docs just leave up to you to figure out on your own.
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.

No. Basically, any ddoc line that begins with a single word followed by ':' is considered the start of a new section, with that word as the section name. Note that the contents of the section are allowed to immediately follow the header on the same line. For example: /** * A most marvelous function * * This function does the most marvelous things to the * parameters you pass in! * Returns: an integer of the most marvelous characteristics. * See also: anotherMarvelousFunc. * * Bugs: this function has some rather marvelous bugs. * * Ddoc also contains some rather marvelous * bugs: * Like the previous sentence. */ int marvelousFunc(A...)(A args) { ... } Run the above through dmd -D to see what happens. :) Basically, there are 5 sections in the above ddoc comment: - the "default" (nameless) section consisting of the first two paragraphs ("A most marvelous function" and "This function does ... you pass in!"). - The "Returns:" section, which contains a single paragraph "an integer of the most marvelous characteristics." - The "See also:" section, consisting of a single word. - The "Bugs:" section, consisting of two paragraphs: this function has some rather marvelous bugs. Ddoc also contains some rather marvelous - Another "bugs:" section, caused by having an isolated word at the beginning of the line followed by ':', containing the paragraph: "Like the previous sentence." This last point is arguably a ddoc bug, but that's how it currently works. So at the very least, this behaviour should be correctly documented. On Sun, Aug 25, 2013 at 04:56:33AM +0200, Andre Artus wrote:
 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.

Ddoc automatically strips the * from the first column when you write a comment like: /** * Summary * * Description * ---- * // code example * int[] arr = [1,2,3,4,5]; * ---- */ This is done before the contents of the comment are parsed into sections. So section names never include an initial '*'. This leads to gotchas like the following: /** Summary This function calculates the value of 17 * 24. */ The output is: Summary This function calculates the value of 17 24. The '*' is missing because ddoc automatically stripped it. Again, this is a quirk of ddoc, and should be documented, whether or not this kind of behaviour is considered a bug. T -- What do you call optometrist jokes? Vitreous humor.
Aug 25 2013