cplusplus / cplusplus/draft

The standard and the DRY principle: header descriptions

Open
#3,321 7 comments 0 reactions 0 assignees View on GitHub

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.