Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[lib] Subheadings in class descriptions #1242

Closed
jensmaurer opened this issue Dec 14, 2016 · 10 comments
Closed

[lib] Subheadings in class descriptions #1242

jensmaurer opened this issue Dec 14, 2016 · 10 comments
Labels
big An issue causing a large set of changes, scattered across most of the text.
Milestone

Comments

@jensmaurer
Copy link
Member

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?

@jensmaurer jensmaurer added the decision-required A decision of the editorial group (or the Project Editor) is required. label Dec 14, 2016
@jensmaurer
Copy link
Member Author

Editorial meeting consensus: Do not repeat a parent heading item in subordinate headings.

@jensmaurer jensmaurer removed the decision-required A decision of the editorial group (or the Project Editor) is required. label Mar 2, 2017
@jensmaurer jensmaurer added this to the C++20 milestone Apr 5, 2017
jensmaurer added a commit to jensmaurer/draft that referenced this issue Nov 2, 2017
zygoloid pushed a commit that referenced this issue Nov 12, 2017
AaronBallman pushed a commit to AaronBallman/draft that referenced this issue Nov 15, 2017
@tkoeppe
Copy link
Contributor

tkoeppe commented Apr 2, 2018

@jensmaurer: What about [container.node]?

@jensmaurer
Copy link
Member Author

jensmaurer commented 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
Copy link
Contributor

tkoeppe commented 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 :-)

zygoloid added a commit that referenced this issue Apr 2, 2018
@zygoloid
Copy link
Member

zygoloid commented Apr 2, 2018

I'm happy with removing node_handle from these headings, as they are not really describing members of some class named node_handle; rather, they're describing members of the exposition-only notion of a "node handle". Done in 2fcacf3.

@JohelEGP
Copy link
Contributor

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
Copy link
Member Author

@JohelEGP, I don't understand the question. Header synopses usually say "Header <blah> synopsis", and that doesn't mention a class name.

@JohelEGP
Copy link
Contributor

I mean the line comments like this:

    // [time.duration], class template duration
    template<class Rep, class Period = ratio<1>> class duration;

@jensmaurer
Copy link
Member Author

@JohelEGP, those comments quote the subclause heading, so those seem fine.

@jensmaurer
Copy link
Member Author

This should be complete now.

@jensmaurer jensmaurer added the big An issue causing a large set of changes, scattered across most of the text. label Nov 27, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
big An issue causing a large set of changes, scattered across most of the text.
Projects
None yet
Development

No branches or pull requests

4 participants