Skip to content
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

Open
gennaroprota opened this issue Oct 23, 2019 · 7 comments
Open

The standard and the DRY principle: header descriptions #3321

gennaroprota opened this issue Oct 23, 2019 · 7 comments

Comments

@gennaroprota
Copy link

gennaroprota commented Oct 23, 2019

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

@jensmaurer
Copy link
Member

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?

@jensmaurer jensmaurer added the decision-required A decision of the editorial group (or the Project Editor) is required. label Oct 23, 2019
@jwakely
Copy link
Member

jwakely commented 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.

Also, should it say "declares" rather than "defines"?

No, I don't think so.

@CaseyCarter
Copy link
Contributor

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 template char_traits: char_traits<char>, char_traits<char8_t>, char_traits<char16_t>, char_traits<char32_t>, and char_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
Copy link
Contributor

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
Copy link
Contributor

CaseyCarter commented 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.

The clause in question is:
image

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 of char_traits, but there's no primary template definition." would be an improvement.

@gennaroprota
Copy link
Author

CaseyCarter wrote:

Formally the headers both declare and define entities, but since defining declarations are a subset of all declarations "define" is more precise than "declare".

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
Copy link
Member

Editorial meeting: Consistently use "The header <blah> has the following contents:" and avoid the lists entirely, which are redundant with the actual headers.

@jensmaurer jensmaurer removed the decision-required A decision of the editorial group (or the Project Editor) is required. label Nov 4, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

5 participants