Description
Several header descriptions in the standard say things like "the header <header>
declares three functions, two classes and defines five macros".
These descriptions add really nothing useful, and can only become wrong under maintenance. Even if numbers are not provided, it may happen e.g. that a description only mention classes and functions but, later, function templates are added.
Here's a list of what are IMHO the problematic ones. I suggest removing them, but, for some of them, I also suggest a replacement in case the removal is not possible:
- In [char.traits.specializations]:
"The header <string>
defines five specializations of the class template
char_traits
: char_traits<char>
, char_traits<char8_t>
,
char_traits<char16_t>
, char_traits<char32_t>
, and char_traits<wchar_t>
."
Suggested replacement:
"The header <string>
defines the following specializations:
char_traits<char>
, char_traits<char8_t>
, char_traits<char16_t>
,
char_traits<char32_t>
, and char_traits<wchar_t>
."
(Also, should it say "declares" rather than "defines"? NB: this question
applies to every description, but I will not repeat it.)
- In [string.classes]:
"The header <string>
defines the basic_string
class template for
manipulating varying-length sequences of char-like objects and five
typedef-names, string
, u8string
, u16string
, u32string
, and wstring
, that
name the specializations basic_string<char>
, basic_string<char8_t>
,
basic_string<char16_t>
, basic_string<char32_t>
, and basic_string<wchar_t>
,
respectively."
Suggested replacement:
"The header <string>
defines facilities for manipulating varying-length
sequences of char-like objects."
- In [associative.general]:
"The header <map>
defines the class templates map
and multimap
; the header
<set>
defines the class templates set
and multiset
."
- In [unord.general]:
"The header <unordered_map>
defines the class templates unordered_map
and
unordered_multimap
; the header <unordered_set>
defines the class templates
unordered_set
and unordered_multiset
."
- In [container.adaptors.general]:
"The headers <queue>
and <stack>
define the container adaptors queue
,
priority_queue
, and stack
."
- In [views.general]:
"The header <span>
defines the view span
."
- In [complex.numbers]:
"The header <complex>
defines a class template, and numerous functions for
representing and manipulating complex numbers."
Suggested replacement:
"The header <complex>
defines facilities for representing and manipulating
complex numbers."
- In [valarray.syn]:
"The header <valarray>
defines five class templates (valarray
,
slice_array
, gslice_array
, mask_array
, and indirect_array
), two classes
(slice
and gslice
), and a series of related function templates for
representing and manipulating arrays of values."
Suggested replacement:
"The header <valarray>
defines facilities for representing and
manipulating arrays of values."
- In [locale.syn]:
"The header <locale>
defines classes and declares functions that
encapsulate and manipulate the information peculiar to a locale."
Suggested replacement:
"The header <locale>
defines facilities that encapsulate and manipulate
the information peculiar to a locale."
- In [input.streams]:
"The header <istream>
defines two types and a function signature that
control input from a stream buffer along with a function template that
extracts from stream rvalues."
Note, too, the use of "function signature" instead of just "function".
- In [output.streams]:
"The header <ostream>
defines a type and several function signatures that
control output to a stream buffer along with a function template that
inserts into stream rvalues."
Same comment as in the previous bullet.
- In [std.manip]:
"The header <iomanip>
defines several functions that support extractors
and inserters that alter information maintained by class ios_base
and its
derived classes."
- In [sstream.syn]:
"The header <sstream>
defines four class templates and eight types that
associate stream buffers with objects of class basic_string
, as described
in 21.3."
- In [fstream.syn]:
"The header <fstream>
defines four class templates and eight types that
associate stream buffers with files and assist reading and writing files."
Activity
jensmaurer commentedon Oct 23, 2019
Well, those intro phrases do offer a little comfort for the unsuspecting reader, although I agree telling about N functions and X parrots is stupid. Plus, those intro phrases are technically normative, which seems at best a stretch.
My suggest would be to rephrase them as notes, removing the numbered items, but keeping the general intro fluff.
@CaseyCarter , @jwakely , what do you think?
jwakely commentedon Oct 24, 2019
I see little benefit to removing these entirely. Removing the number of things declared seems like a minor improvement in terms of maintainability. Talking about "function signatures" seems wrong.
But I'd prefer not to drop the paragraphs entirely.
No, I don't think so.
CaseyCarter commentedon Oct 24, 2019
The counts and mentions of entity kinds should go for sure. I'm also not fond of set enumerations ("The header
<string>
defines five specializations of the class templatechar_traits
:char_traits<char>
,char_traits<char8_t>
,char_traits<char16_t>
,char_traits<char32_t>
, andchar_traits<wchar_t>
.") even in the absence of counts. A list of names that's literally repeated right there in the synopsis adds no value at all: tell me what the defining property of this set is, tell me why it has the members it has, sure - but a list of members in the introduction of a synopsis whose only job is to be a list members is just noise.Formally the headers both declare and define entities, but since defining declarations are a subset of all declarations "define" is more precise than "declare".
AlisdairM commentedon Oct 24, 2019
I think listing the restricted set of supported specializations may be relevant, as it is unusual to restrict our support in such a way. That does not mean I oppose a clean-up, just that I would appreciate a cleanup that preserves (and perhaps better motivates) those specific lists. I'm also not the one doing the work, so weight my preferences accordingly ;)
CaseyCarter commentedon Oct 24, 2019
The clause in question is:

It's a synopsis with the five specializations of
char_traits
, and then a sentence that repeats exactly the information from that synopsis. While I agree the restricted set of specializations is noteworthy, I don't think back-to-back repetition of the same information communicates anything useful. A note that says, "Hey, pay attention: we define some explicit specializations ofchar_traits
, but there's no primary template definition." would be an improvement.gennaroprota commentedon Oct 25, 2019
CaseyCarter wrote:
A header is the subject of a #include directive, whose behavior, informally, is to put the header contents in its place. For functions, this means that a declaration must be provided, not a definition, unless the function is inline. We might perhaps say "the header
<header>
provides" or "the header<header>
makes available" (in case we want to keep some sort of general description)?jensmaurer commentedon Nov 4, 2019
Editorial meeting: Consistently use "The header <blah> has the following contents:" and avoid the lists entirely, which are redundant with the actual headers.