The standard and the DRY principle: header descriptions
Nobody has claimed this yet.
- Dominant language
- TeX
- Stars
- 221
- Forks
- 813
- Avg merge
- 16h 4m
- Merged PRs (30d)
- 36
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."
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Search the standard source for the listed section anchors, including [char.traits.specializations], [string.classes], [associative.general], and the stream and synopsis sections. Review each header description against the issue's proposed wording, then verify that the listed descriptions no longer depend on fragile counts or inaccurate terminology.】【。
Written by the indexing model from the issue text.
Assessment
- Tech stack
- tex
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 45/100