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
The standard and the DRY principle: header descriptions #3321
Comments
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. @CaseyCarter , @jwakely , what do you think? |
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. |
The counts and mentions of entity kinds should go for sure. I'm also not fond of set enumerations ("The header Formally the headers both declare and define entities, but since defining declarations are a subset of all declarations "define" is more precise than "declare". |
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 ;) |
It's a synopsis with the five specializations of |
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 |
Editorial meeting: Consistently use "The header <blah> has the following contents:" and avoid the lists entirely, which are redundant with the actual headers. |
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 templatechar_traits
:char_traits<char>
,char_traits<char8_t>
,char_traits<char16_t>
,char_traits<char32_t>
, andchar_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>
, andchar_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 thebasic_string
class template formanipulating varying-length sequences of char-like objects and five
typedef-names,
string
,u8string
,u16string
,u32string
, andwstring
, thatname the specializations
basic_string<char>
,basic_string<char8_t>
,basic_string<char16_t>
,basic_string<char32_t>
, andbasic_string<wchar_t>
,respectively."
Suggested replacement:
"The header
<string>
defines facilities for manipulating varying-lengthsequences of char-like objects."
- In [associative.general]:
"The header
<map>
defines the class templatesmap
andmultimap
; the header<set>
defines the class templatesset
andmultiset
."- In [unord.general]:
"The header
<unordered_map>
defines the class templatesunordered_map
andunordered_multimap
; the header<unordered_set>
defines the class templatesunordered_set
andunordered_multiset
."- In [container.adaptors.general]:
"The headers
<queue>
and<stack>
define the container adaptorsqueue
,priority_queue
, andstack
."- In [views.general]:
"The header
<span>
defines the viewspan
."- In [complex.numbers]:
"The header
<complex>
defines a class template, and numerous functions forrepresenting and manipulating complex numbers."
Suggested replacement:
"The header
<complex>
defines facilities for representing and manipulatingcomplex numbers."
- In [valarray.syn]:
"The header
<valarray>
defines five class templates (valarray
,slice_array
,gslice_array
,mask_array
, andindirect_array
), two classes(
slice
andgslice
), and a series of related function templates forrepresenting and manipulating arrays of values."
Suggested replacement:
"The header
<valarray>
defines facilities for representing andmanipulating arrays of values."
- In [locale.syn]:
"The header
<locale>
defines classes and declares functions thatencapsulate and manipulate the information peculiar to a locale."
Suggested replacement:
"The header
<locale>
defines facilities that encapsulate and manipulatethe information peculiar to a locale."
- In [input.streams]:
"The header
<istream>
defines two types and a function signature thatcontrol 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 thatcontrol 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 extractorsand inserters that alter information maintained by class
ios_base
and itsderived classes."
- In [sstream.syn]:
"The header
<sstream>
defines four class templates and eight types thatassociate stream buffers with objects of class
basic_string
, as describedin 21.3."
- In [fstream.syn]:
"The header
<fstream>
defines four class templates and eight types thatassociate stream buffers with files and assist reading and writing files."
The text was updated successfully, but these errors were encountered: