Repository navigation
[lib] Subheadings in class descriptions #1242
Description
We have both:
- Class template blah
-- blah constructors
(etc)
and
- Class template blah
-- Construction and assignment [note: omitting "blah" in subordinate headings]
(etc)
[basic.string] is an example for the former, [string.view.template] is an example for the latter.
Which way is the "right" way?
Activity
jensmaurer commentedon Mar 2, 2017
Editorial meeting consensus: Do not repeat a parent heading item in subordinate headings.
[array] Dissolve single-item subclauses.
[array] Dissolve single-item subclauses.
[array] Dissolve single-item subclauses.
tkoeppe commentedon Apr 2, 2018
@jensmaurer: What about [container.node]?
jensmaurer commentedon Apr 2, 2018
@tkoeppe: [container.node] is odd. It specifies an exposition-only class node_handle, which need not exist under this name. Everywhere else in the vicinity, we specify requirements on classes or class templates by specifying the valid operations on them, instead of showing a class synopsis.
I'd like to point out that the superordinate heading says "Node handles" and the subordinate headings say "node_handle", which is not exactly a repetition (although quite close).
tkoeppe commentedon Apr 2, 2018
@jensmaurer: Yeah, that's true. Not sure what to do here. @zygoloid: Opinions?
My primary goal here is to get rid of a bold-italic-teletype font requirement, which we cannot satisfy :-)
[container.node] Remove placeholder class name from subheadings.
zygoloid commentedon Apr 2, 2018
I'm happy with removing
node_handlefrom these headings, as they are not really describing members of some class namednode_handle; rather, they're describing members of the exposition-only notion of a "node handle". Done in 2fcacf3.JohelEGP commentedon Jun 27, 2018
Do you have a stance on the repetition in the headers' synopsis? That repetition might provide some context that's implicitly available in the subclauses for being nested.
jensmaurer commentedon Jun 28, 2018
@JohelEGP, I don't understand the question. Header synopses usually say "Header <blah> synopsis", and that doesn't mention a class name.
JohelEGP commentedon Jun 28, 2018
I mean the line comments like this:
jensmaurer commentedon Jun 28, 2018
@JohelEGP, those comments quote the subclause heading, so those seem fine.
jensmaurer commentedon Nov 27, 2018
This should be complete now.