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.
