ISO/IEC JTC1 SC22 WG21 N3394 = 12-0084 - 2012-06-12
Alberto Ganesh Barbati, <ganesh at barbati dot net>Several existing implementations provide ways to annotate entities whose use is discouraged. The goal is achieved using an implementation-specific decoration syntax. For example:
Compiler | Simple deprecation | Deprecation with message |
---|---|---|
gcc and clang | __attribute__((deprecated))
int a;
|
__attribute__((deprecated("message")))
int a;
|
Visual Studio | __declspec(deprecated) int a; |
__declspec(deprecated("message"))
int a; |
Embarcadero (1) |
int a [[deprecated]] ; |
int a [[deprecated("message")]] ; |
(1) Embarcadero currently implements the pre-N3067 C++0x
attribute syntax.
Despite the different syntaxes, the behavior is quite consistent in all the above mentioned compilers:
Given that:
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.
The name deprecated
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:
"Normative for the current edition of the Standard, but not guaranteed to be part of the Standard in future revisions."
This definition is not seen to match with what the proposed deprecated
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 deprecated
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 deprecated
and because both issues are related to the same key paragraph.
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:
Thanks to Alisdair Meredith for reviewing the paper and for his help in improving the wording. The proposed definition of the term "deprecated" has been suggested by William M. Miller.
The wording proposed in this section is based on the FDIS, paper N3290.
Add a new subsection in 7.6 Attributes [dcl.attr]:
Deprecated attribute [dcl.attr.deprecated]
The attribute-token
deprecated
can be used to mark names and entities whose use is still allowed, but is discouraged for some reason. [Note: in particular,deprecated
is appropriate for names and entities that are deemed obsolescent or unsafe. —end note] It shall appear at most once in each attribute-list. An attribute-argument-clause may be present and, if present, it shall have the form:( string-literal )
[Note: the string-literal in the attribute-argument-clause could be used to explain the rationale for deprecation and/or to suggest a replacing entity. —end note]
The attribute may be applied to:
- classes
- typedef-names
- variables
- functions
- namespaces
- enumerations
- enumerators
- templates
- template specializations
A name or entity declared without the deprecated attribute can later be re-declared with the attribute and vice-versa. [Note: 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. —end note] Redeclarations using different forms of the attribute (with or without the attribute-argument-clause or with different attribute-argument-clauses) are allowed.
The presence of the attribute has no normative effect. Implementations may use the
deprecated
attribute to produce a diagnostic message in case a name or entity is used by the program after the first declaration that specifies the attribute. The diagnostic message may include the text provided within the attribute-argument-clause of anydeprecated
attribute applied to the name or entity.
Change Annex D [depr], paragraph 2:
These are deprecated features, where deprecated is defined as: Normative for the current edition of the Standard, but
not guaranteed to be partbeen identified as a candidate for removal from future revisions of the Standardin future revisions. An implementation may declare library names and entities described in this section with the attributedeprecated
([dcl.attr.deprecated]).