Skip to content

The standard and the DRY principle: header descriptions #3321

Open
@gennaroprota

Description

@gennaroprota

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

jensmaurer commented on Oct 23, 2019

@jensmaurer
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?

added
decision-requiredA decision of the editorial group (or the Project Editor) is required.
on Oct 23, 2019
jwakely

jwakely commented on Oct 24, 2019

@jwakely
Member

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

CaseyCarter commented on Oct 24, 2019

@CaseyCarter
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

AlisdairM commented on Oct 24, 2019

@AlisdairM
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

CaseyCarter commented on Oct 24, 2019

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

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

gennaroprota commented on Oct 25, 2019

@gennaroprota
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

jensmaurer commented on Nov 4, 2019

@jensmaurer
Member

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

removed
decision-requiredA decision of the editorial group (or the Project Editor) is required.
on Nov 4, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @AlisdairM@CaseyCarter@jwakely@gennaroprota@jensmaurer

        Issue actions

          The standard and the DRY principle: header descriptions · Issue #3321 · cplusplus/draft