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

[H. S. Teoh]

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.