<html>
  <head>
    <meta content="text/html; charset=us-ascii" http-equiv="content-type">
    <style type="text/css">

body { color: #000000; background-color: #FFFFFF; }
del { text-decoration: line-through; color: #8B0040; }
ins { text-decoration: underline; color: #005100; }

p.example { margin-left: 2em; }
pre.example { margin-left: 2em; }
div.example { margin-left: 2em; }

code.extract { background-color: #F5F6A2; }
pre.extract { margin-left: 2em; background-color: #F5F6A2;
  border: 1px solid #E1E28E; }

p.function { }
.attribute { margin-left: 2em; }
.attribute dt { float: left; font-style: italic;
  padding-right: 1ex; }
.attribute dd { margin-left: 0em; }

blockquote.std { color: #000000; background-color: #F1F1F1;
  border: 1px solid #D1D1D1;
  padding-left: 0.5em; padding-right: 0.5em; }
blockquote.stddel { text-decoration: line-through;
  color: #000000; background-color: #FFEBFF;
  border: 1px solid #ECD7EC;
  padding-left: 0.5empadding-right: 0.5em; ; }

blockquote.stdins { text-decoration: underline;
  color: #000000; background-color: #C8FFC8;
  border: 1px solid #B3EBB3; padding: 0.5em; }

table { border: 1px solid black; border-spacing: 0px;
  margin-left: auto; margin-right: auto; }
th { text-align: left; vertical-align: top;
  padding-left: 0.8em; border: none; }
td { text-align: left; vertical-align: top;
  padding-left: 0.8em; border: none; }

</style> <title>[[deprecated]] attribute</title>
  </head>
  <body lang="en">
    <h1>[[deprecated]] attribute</h1>
    <p>Document: ISO/IEC JTC1 SC22 WG21 N3760</p>
    <p>Date: 2013-09-01 </p>
    <address> Alberto Ganesh Barbati, &lt;ganesh at barbati dot net&gt; </address>
    <p>This is an update of <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3394.html">N3394</a>,
      bearing changes proposed in the pre-Chicago Drafting Review Teleconference
      of 2013-08-26. The main difference is that the list of the cases where the
      attribute can be used has changed, by removing namespaces, enumerators,
      templates and adding non-static data members.</p>
    <h2>Motivation</h2>
    <p> Several existing implementations provide ways to annotate entities whose
      use is discouraged. The goal is achieved using an implementation-specific
      decoration syntax. For example:</p>
    <table border="0" cellpadding="4" cellspacing="4">
      <tbody>
        <tr>
          <th scope="col">Compiler</th>
          <th scope="col">Simple deprecation</th>
          <th scope="col">Deprecation with message</th>
        </tr>
        <tr>
          <th style="vertical-align:middle" scope="row">gcc and clang</th>
          <td style="vertical-align:middle"><code>__attribute__((deprecated))
              int a;</code><code></code><code></code><br>
          </td>
          <td style="vertical-align:middle"><code>__attribute__((deprecated("message")))
              int a;</code><code></code><code></code><br>
          </td>
        </tr>
        <tr>
          <th style="vertical-align:middle" scope="row">Visual Studio</th>
          <td style="vertical-align:middle"><code>__declspec(deprecated) int a;</code></td>
          <td style="vertical-align:middle"><code>__declspec(deprecated("message"))
              int a;</code></td>
        </tr>
        <tr>
          <th style="vertical-align:middle" scope="row">Embarcadero<sup> (1)</sup><br>
          </th>
          <td style="vertical-align:middle"><code>int a </code><code>[[deprecated]]</code><code>;</code></td>
          <td style="vertical-align:middle"><code>int a </code><code>[[deprecated("message")]]</code><code>;</code></td>
        </tr>
      </tbody>
    </table>
    <p><sup>(1)</sup> Embarcadero currently implements the pre-N3067 C++0x
      attribute syntax.<br>
    </p>
    <p>Despite the different syntaxes, the behavior is quite consistent in all
      the above mentioned compilers:</p>
    <ol>
      <li>if an entity declared as deprecated is used in the program, the
        compiler emits a diagnostic message;</li>
      <li>if the "deprecation with message" syntax is used, the diagnostic
        message includes the text provided as the attribute argument;<br>
      </li>
      <li>the diagnostic message is considered by default a "warning" and usual
        compiler-specific settings can be used to either disable the message or
        escalate it to an error message.</li>
    </ol>
    <p>Given that:</p>
    <ol>
      <li>User experience with this annotation has proven it to be useful;</li>
      <li>C++11 introduces a standard syntax for attributes, whose aim is
        precisely to overcome the limitations of implementation-specific
        annotation syntaxes;</li>
      <li>This annotation fits in the guidelines for new attributes described in
        paper <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2761.pdf">N2761</a>
        and is indeed mentioned there as a good candidate;</li>
      <li>This annotation has no actual effect beside providing diagnostic
        messages; as such it provides no implementation challenge as it might be
        simply ignored without affecting the semantic of a conformant program.</li>
    </ol>
    <p>It is hereby proposed to add a new attribute to standardize the existing
      practice and provide a syntax that is portable among all C++11
      implementations. </p>
    <h2>Discussion</h2>
    <p>The name <code>deprecated</code> has been chosen because it is already
      used by the four mentioned implementations and possibly many more. The
      meaning of the term appears to be well-understood by the end users.
      Nonetheless, strong objections were raised on the c++-ext reflector
      because the term "deprecated" appears to be normatively used in the
      Standard in annex D, para 2 with the following definition:</p>
    <blockquote>
      <p>"Normative for the current edition of the Standard, but not guaranteed
        to be part of the Standard in future revisions."</p>
    </blockquote>
    <p>This definition is not seen to match with what the proposed <code>deprecated</code>
      attribute is supposed to mean. As a counter-objection it has been noted
      that the definition above is actually void of any meaning, because it may
      be applied to any normative statement in the standard. Moreover the
      definition doesn't capture the intent of Annex D, that is to present
      features that have been deliberately selected for a possible future
      removal and are retained uniquely for backward compatibility purposes.
      This paper addresses this issue by suggesting a different definition of
      the term "deprecated". This suggestion is expected to be slightly
      controversial and it is inessential to the introduction of the <code>deprecated</code>
      attribute, so it could probably be treated as a separate issue. However,
      it might still be beneficial to handle both issues in the same paper, to
      address the objections about the choice of the name <code>deprecated</code>
      and because both issues are related to the same key paragraph.<br>
    </p>
    <p>On the c++-ext reflector, there was also a discussion about requiring
      mandatory diagnostic messages rather than "warnings". This paper doesn't
      propose mandatory diagnostic for the following reasons:</p>
    <ol>
      <li>the mere idea has encountered strong opposition on the reflector with
        several "over my dead body" objections;<br>
      </li>
      <li>it would be an innovation and not the standardization of existing
        practice: people that are happy with their tools would be discouraged
        from using the new syntax if that would change the way they work, making
        the standardization effort pointless;<br>
      </li>
      <li>as mentioned above, most implementation already provide
        implementation-specific ways to escalate these "warning" messages to
        "error" messages; having the user rely on them seems a better option;</li>
      <li>mandatory diagnostics would require the specification of a complete
        set of rules for when a deprecated entity is "used"; this effort would
        likely outweigh the benefit of specifying the feature, which lies in an
        area ripe for different implementations to compete on QoI.<br>
      </li>
    </ol>
    <h2>Acknowledgements</h2>
    <p>Thanks to Alisdair Meredith for reviewing the paper and for his help in
      improving the wording. Thanks to William M. Miller for his support during
      the drafting process and for the proposed definition of the term
      "deprecated" (which has already been included in N3691, so it has been
      removed from this paper).</p>
    <h2>Proposed changes</h2>
    <p>The wording proposed in this section is based on the latest draft, paper
      <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3691.pdf">N3691</a>.<br>
    </p>
    <p>Add a new subsection in 7.6 Attributes [dcl.attr]: </p>
    <blockquote class="stdins">
      <h3>Deprecated attribute [dcl.attr.deprecated]</h3>
      <p>The <var>attribute-token</var> <code>deprecated</code> can be used to
        mark names and entities whose use is still allowed, but is discouraged
        for some reason. [<i>Note:</i> in particular, <code>deprecated</code>
        is appropriate for names and entities that are deemed obsolescent or
        unsafe. &#8212;<i>end note</i>] It shall appear at most once in each <var>attribute-list</var>.
        An <var>attribute-argument-clause</var> may be present and, if present,
        it shall have the form: </p>
      <pre><code>    ( <var>string-literal</var> )</code></pre>
      <p>[<i>Note:</i> the <var>string-literal</var> in the <var>attribute-argument-clause</var>
        could be used to explain the rationale for deprecation and/or to suggest
        a replacing entity. &#8212;<i>end note</i>]</p>
      <p>The attribute may be applied to the declaration of a class, a <var>typedef-name</var>,
        a variable, a non-static data member, a function, an enumeration, or a
        template specialization.</p>
      <p>A name or entity declared without the <code>deprecated</code>
        attribute can later be re-declared with the attribute and vice-versa. [<i>Note:</i>
        Thus, an entity initially declared without the attribute can be marked
        as deprecated by a subsequent redeclaration. However, after an entity is
        marked as deprecated, later redeclarations do not un-deprecate the
        entity. &#8212;<i>end note</i>]&nbsp; Redeclarations using different forms of
        the attribute (with or without the <var>attribute-argument-clause</var>
        or with different <var>attribute-argument-clause</var>s) are allowed.</p>
      <p>[<i>Note:</i> Implementations may use the <code>deprecated </code>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 within
        the <var>attribute-argument-clause</var> of any <code>deprecated</code>
        attribute applied to the name or entity. &#8212;<i>end note</i>]</p>
    </blockquote>
    <p>Change Annex D [depr], paragraph 2:</p>
    <blockquote class="std">
      <p>These are deprecated features, where <dfn>deprecated</dfn> is defined
        as: Normative for the current edition of the Standard, but having been
        identified as a candidate for removal from future revisions. <ins>An
          implementation may declare library names and entities described in
          this section with the <code>deprecated</code> attribute
          ([dcl.attr.deprecated]).</ins></p>
    </blockquote>
  </body>
</html>
