Which codeblocks should contain "namespace std"?

[tkoeppe]

Header synopses always contain namespace std { .... When we describe the header content in detail, we often repeat namespace std {, e.g. in "Class template vector".

However, we sometimes don't repeat the namespace for specifications. Examples are "optional", "polymorphic_memory_resource", and "linear_congruential_engine".

(Note that I am not talking about itemdecls; those never state the namespace.)

We should decide whether to state the namespace in those detailed definitions, and then apply that style consistently and record it in the wiki.

I think the majority use at the moment is to state the namespace, but that doesn't need to be a deciding factor. Note also that some class templates live in further nested namespaces, so there may be some value in being explicit.

[tkoeppe]

My gut feeling is that we generally want namespace std {. Could someone perhaps attempt a quick survey to see how many "class template Foo" codeblocks are missing the namespace? I can think of "class template optional" and "class any" of the top of my head.

[jensmaurer]

Rough overview:

• rSec involving "Class template" followed by "class": 159 occurrences
• rSec involving "Class template" followed by "namespace" followed by "class": 101 occurrences

That seems we're missing 58 "namespace" things.

$ sed -n '/rSec.*{Class template/,+6 { /namespace/,+6 { /class/p } }' *.tex | wc -l
101

[tkoeppe]

Ah, that's quite a lot actually, to a point where I'd say there's no clear preference.

[jensmaurer]

However, I do find the arguments above compelling, in particular the fact that some classes are in nested namespaces. Adding namespce std { in a few places (plus adjusting the indentation) seems like a good general approach.

[jwakely]

IMHO consistently showing the namespace would be better.

[tkoeppe]

I agree, I would certainly like the namespace to show, but if this is more than a handful of local fixes, then I'm not in a hurry to get onto it just now.

[jensmaurer]

The verbose part is the indentation changes that come along with namespace std {.

[zygoloid]

I have a slight hesitation with this direction: for itemdecls, we don't list the namespace (nor class) and it would not be useful to do so. Consistency would indicate that we don't list the namespace std { for class definitions either; to see where something is made available, you have to find the corresponding synopsis.

However, the argument that we have nested namespaces within std is also persuasive.

I suggest that for now we normalize towards including the namespace for class definitions (and enum definitions) but not for function declarations and similar things in itemdecls.

As a more general rule: if the declaration itself is a definition-like thing providing specification in and of itself, then it gets a namespace. If it's just a backreference to something specified elsewhere to anchor the words to a specific declaration, then it doesn't. Consistently applied, that'd mean we'd write either:

namespace std {
  template<typename charT, class traits, class Allocator>
  basic_string<charT, traits, Allocator>&
  basic_string<charT, traits, Allocator>::operator=(charT c) {
    return *this = basic_string(1, c);
  }
}

or

basic_string& operator=(charT c);

Returns: *this = basic_string(1, c).

(but I'm not suggesting we actually ever use the first formulation). This has a certain pleasing parallel with the rules of C++ for out-of-line vs inline declarations.

[tkoeppe]

That seems like a good general rule.

Concretely, I think itemdecls are only ever used as backreferences (and it should stay that way). New specifications always use codeblocks, though some of them are still missing full namespaces at the moment.