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

Consider moving "in addition ... included" content into synopses, deleting prose text #3683

Open
tkoeppe opened this issue Feb 15, 2020 · 10 comments
Assignees
Labels
decision-required A decision of the editorial group (or the Project Editor) is required.

Comments

@tkoeppe
Copy link
Contributor

tkoeppe commented Feb 15, 2020

See #3670: in LWG review it emerged that the pattern of "In addition to ... available when the header <foo> is included" is fairly widely used (as opposed to repeating declarations in synopses). We may like to consider a review of the situation. The other places that use "in addition..." wording are:

tuple.helper p6, p8
iterator.range p1
range.access p1

@CaseyCarter
Copy link
Contributor

CaseyCarter commented Feb 18, 2020

Note to self: If the "In addition to..." form is undesirable and we decide to replace all occurrences, the P/R of lwg 3378 should be changed accordingly.

@jensmaurer
Copy link
Member

I favor repeating the declaration in the synopsis instead of prose text "In addition to ... available".

@JohelEGP
Copy link
Contributor

JohelEGP commented Mar 2, 2020

I propose introducing exposition-only headers to avoid duplication that easily becomes outdated, as we've seen recently in various issues.

Example of definition and use:

23 Iterators library [iterators]

23.7 Range access [iterator.range]

In addition to being available via inclusion of the <iterator> header, the function templates in [iterator.range] are available when a header including the exposition-only header <range-access> is included:

22.3.2 Header <array> synopsis [array.syn]

#include <compare>              // see [compare.syn]
#include <initializer_list>     // see [initializer.list.syn]
#include <range-access>         // see [iterator.range]

@cpplearner
Copy link
Contributor

template<class T> struct atomic; is declared in [memory.syn]. Does that mean std::atomic is required to be available if <memory> is included? If so, does that mean the partial specialization std::atomic<T*> is available? What about the specializations for integers and floating-point types?

@JohelEGP
Copy link
Contributor

JohelEGP commented May 23, 2020

There's also meta.trans.other p2 for unwrap_reference and family.

@jensmaurer jensmaurer added the decision-required A decision of the editorial group (or the Project Editor) is required. label May 24, 2020
@tkoeppe
Copy link
Contributor Author

tkoeppe commented May 28, 2021

@jwakely: Not sure why you're assigned here, but is LWG OK with this direction?

@jensmaurer
Copy link
Member

Editorial meeting: Mechanically replace prose text with duplication of declaration in synopses.

@jensmaurer jensmaurer removed the decision-required A decision of the editorial group (or the Project Editor) is required. label May 28, 2021
@jwakely
Copy link
Member

jwakely commented May 28, 2021

Does that mean std::atomic is required to be available if <memory> is included?

No, only the declaration.

If so, does that mean the partial specialization std::atomic<T*> is available? What about the specializations for integers and floating-point types?

No and no.

@jwakely
Copy link
Member

jwakely commented May 28, 2021

There are a few suggestions here, I assume the exposition only header is not the suggested direction.

I can see the advantage in repeating declarations, but it does raise the question of when a declaration in a header synopsis means the feature is available (i.e., in practice, when it's defined) or only declared. As noted above, <memory> declares atomic in order to define a specialization, but that is not intended to mean the primary template is defined. But how do we know when a declaration in a synopsis implies a definition too?

@jensmaurer
Copy link
Member

"But how do we know when a declaration in a synopsis implies a definition too?"

Good point. How do we know that, in general? The header synopsis is often, but not always, near the definition and the specification thereof, but that's certainly a stretch.

So, we have the case that showing the declaration of std::atomic in <memory> just means the declaration is available. (Note there is intro text that says that an implementation must provide suitable definitions for everything that is declared.)
How does that differ from the presentation of <atomic>, which also just shows a bunch of declarations?

This concern mostly applies to class (template) declarations/definitions and similar. For function declarations, there seems to be little doubt that showing a declaration implies having a definition available, but that could of course be provided out-of-line, as usual for function definitions.

It seems to me the "declaration-only" cases of std::atomic are the odd ones that need special treatment (maybe a special comment // no definition or so).

@jensmaurer jensmaurer added the decision-required A decision of the editorial group (or the Project Editor) is required. label May 28, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
decision-required A decision of the editorial group (or the Project Editor) is required.
Projects
None yet
Development

No branches or pull requests

6 participants