[dcl.attr] Introduce 'Recommended practice' paragraphs.

Author: jensmaurer

source/declarations.tex

@@ -8766,13 +8766,12 @@
 \grammarterm{attribute-argument-clause}{s}) are allowed.
 
 \pnum
-\begin{note}
-Implementations may use the \tcode{deprecated} attribute to produce a diagnostic
+\recommended
+Implementations should use the \tcode{deprecated} attribute to produce a diagnostic
 message in case the program refers to a name or entity other than to declare it, after a
-declaration that specifies the attribute. The diagnostic message may include the text provided
+declaration that specifies the attribute. The diagnostic message should include the text provided
 within the \grammarterm{attribute-argument-clause} of any \tcode{deprecated} attribute applied
 to the name or entity.
-\end{note}
 
 \rSec2[dcl.attr.fallthrough]{Fallthrough attribute}
 \indextext{attribute!fallthrough}
@@ -8796,14 +8795,13 @@
 The program is ill-formed if there is no such statement.
 
 \pnum
-\begin{note}
-The use of a fallthrough statement is intended to suppress
+\recommended
+The use of a fallthrough statement should suppress
 a warning that an implementation might otherwise issue
 for a case or default label that is reachable
 from another case or default label along some path of execution.
 Implementations should issue a warning
 if a fallthrough statement is not dynamically reachable.
-\end{note}
 
 \pnum
 \begin{example}
@@ -8854,7 +8852,7 @@
 that contains the \grammarterm{attribute-token} \tcode{unlikely}.
 
 \pnum
-\begin{note}
+\recommended
 The use of the \tcode{likely} attribute
 is intended to allow implementations to optimize for
 the case where paths of execution including it
@@ -8869,6 +8867,7 @@
 that does not include such an attribute on a statement or label.
 A path of execution includes a label
 if and only if it contains a jump to that label.
+\begin{note}
 Excessive usage of either of these attributes
 is liable to result in performance degradation.
 \end{note}
@@ -8914,6 +8913,14 @@
 a function, an enumeration, or an enumerator.
 
 \pnum
+A name or entity declared without the \tcode{maybe_unused} attribute
+can later be redeclared with the attribute
+and vice versa.
+An entity is considered marked
+after the first declaration that marks it.
+
+\pnum
+\recommended
 For an entity marked \tcode{maybe_unused},
 implementations should not emit a warning
 that the entity or its structured bindings (if any)
@@ -8922,13 +8929,6 @@
 implementations should not emit such a warning unless
 all of its structured bindings are unused.
 
-\pnum
-A name or entity declared without the \tcode{maybe_unused} attribute
-can later be redeclared with the attribute
-and vice versa.
-An entity is considered marked
-after the first declaration that marks it.
-
 \pnum
 \begin{example}
 \begin{codeblock}
@@ -8992,18 +8992,19 @@
 \end{itemize}
 
 \pnum
-\begin{note}
+\recommended
 Appearance of a nodiscard call as
 a potentially-evaluated discarded-value expression\iref{expr.prop}
 is discouraged unless explicitly cast to \tcode{void}.
 Implementations should issue a warning in such cases.
+\begin{note}
 This is typically because discarding the return value
 of a nodiscard call has surprising consequences.
+\end{note}
 The \grammarterm{string-literal}
 in a \tcode{nodiscard} \grammarterm{attribute-argument-clause}
-is intended to be used in the message of the warning
+should be used in the message of the warning
 as the rationale for why the result should not be discarded.
-\end{note}
 
 \pnum
 \begin{example}
@@ -9053,10 +9054,11 @@
 The function may
 terminate by throwing an exception.
 \end{note}
-\begin{note}
+
+\pnum
+\recommended
 Implementations should issue a
 warning if a function marked \tcode{[[noreturn]]} might return.
-\end{note}
 
 \pnum
 \begin{example}

source/macros.tex

@@ -269,6 +269,7 @@
 %% Library function descriptions
 \newcommand{\Fundescx}[1]{\textit{#1}}
 \newcommand{\Fundesc}[1]{\Fundescx{#1:}\space}
+\newcommand{\recommended}{\Fundesc{Recommended practice}}
 \newcommand{\required}{\Fundesc{Required behavior}}
 \newcommand{\requires}{\Fundesc{Requires}}
 \newcommand{\constraints}{\Fundesc{Constraints}}