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

[tkoeppe]

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]

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]

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

[JohelEGP]

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]

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]

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

[tkoeppe]

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

[jensmaurer]

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

[jwakely]

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]

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]

"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).