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.
