diff --git a/wording-guidelines.md b/wording-guidelines.md index 8cf33f5870..9e731d5b6d 100644 --- a/wording-guidelines.md +++ b/wording-guidelines.md @@ -192,29 +192,74 @@ violation means non-conformance of the implementation. In the standard library, "shall" establishes a precondition; when violated, the program has undefined behavior. -Do not use "in" when nested constructs are not supposed to be in -scope. - -**Example (bad):** -> X shall not appear in the expression - -covers lambda bodies nested in the expression, which is often undesirable. - Use a recursive definition of a term or phrase to clearly specify how a rule applies to a recursive construct such as an expression or block. -Use "of" to uniquely identify top-level grammar components, without -risk of unwanted recursion. +### "in" vs. "of" + +We use two different prepositions to put parts of the syntax in relation: + +
+
of
+
specifies a direct relationship between constructs
+ +
in
+
specifies a nested relationship between constructs
+
**Example:** -> The _nested-name-specifier_ of a _qualified-id_ ... + + +> the *type-specifier* in the *parameter-declaration* of a *template-parameter* + +This wording is chosen because a *parameter-declaration* +appears directly in the definition of *template-parameter*, +and *type-specifier* is nested several levels deep into *parameter-declaration* +(*type-specifier* → *defining-type-specifier* → *decl-specifier* → *decl-specifier-seq* +→ *parameter-declaration*). -does not cover any _nested-name-specifier_ nested -within the top-level _nested-name-specifier_. +> [!CAUTION] +> Do not use "in" when nested constructs are not supposed to be in scope. +> +> **Example (bad):** +> > X shall not appear in the expression +> +> covers lambda bodies nested in the expression, which is often undesirable. + +> [!TIP] +> "of" can be chained to describe nested relationships, like +> > *type-specifier* of a *defining-type-specifier* of a *decl-specifier*. + +### "names", "denotes", and "designates" + +There are several words used to describe lookup: + +
+
(to) name
+
means that declarations are found by name
+ +
(to) denote ([basic.pre])
+
means to name an entity, but also "see through" type aliases and namespace aliases
+ +
(to) designate ([basic.splice])
+
means to denote in a splice-specifier what a reflection represents, +or simply for a name to denote something +(that is, "designate" is universal and works for either case)
+
+ +**Example:** +- the *type-specifier* `std::int32_t` names the type alias `std::int32_t` +- the *type-specifier* `std::int32_t` denotes the type `int` or some other signed integer type +- the *type-specifier* `int` designates type `int` +- the *splice-specifier* `[: ^^int :]` designates type `int` +- the *splice-specifier* `[: ^^std::int32_t :]` designates the type denoted by `std::int32_t` +> [!NOTE] +> The least powerful term should be chosen when in doubt. +> For example, we can say "`T` designates type `int`", but "denotes" is preferred. -## Specific words and phrases +### Specific words and phrases
ill-formed, no diagnostic required