From: John McCall <rjmccall@apple.com>
Date: Mon, 8 Nov 2010 19:48:17 +0000 (+0000)
Subject: Document Clang's support for attributes on individual enumerators and
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=4820908be98f340a4c2a563a622ae693a7219c50;p=clang

Document Clang's support for attributes on individual enumerators and
tweak the documentation for deprecation-with-message.  Provide __has_feature
tests for both.  rdar://problem/8605692



git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@118435 91177308-0d34-0410-b5e6-96231b3b80d8
---

diff --git a/docs/LanguageExtensions.html b/docs/LanguageExtensions.html
index f27a570539..c2e217bd6b 100644
--- a/docs/LanguageExtensions.html
+++ b/docs/LanguageExtensions.html
@@ -23,7 +23,8 @@ td {
 <li><a href="#has_include">Include File Checking Macros</a></li>
 <li><a href="#builtinmacros">Builtin Macros</a></li>
 <li><a href="#vectors">Vectors and Extended Vectors</a></li>
-<li><a href="#deprecated">Deprecated and Unavailable attribute with Message</a></li>
+<li><a href="#deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> attributes</a></li>
+<li><a href="#attributes-on-enumerators">Attributes on enumerators</a></li>
 <li><a href="#checking_language_features">Checks for Standard Language Features</a></li>
   <ul>
   <li><a href="#cxx_exceptions">C++ exceptions</a></li>
@@ -286,6 +287,7 @@ float4 foo(float2 a, float2 b) {
   c.yw = b;
   return c;
 }
+</pre>
 </blockquote>
 
 <p>Query for this feature with __has_feature(attribute_ext_vector_type).</p>
@@ -293,12 +295,51 @@ float4 foo(float2 a, float2 b) {
 <p>See also <a href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p>
 
 <!-- ======================================================================= -->
-<h2 id="deprecated">Deprecated and Unavailable attribute with Message</h2>
+<h2 id="deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> Attributes</h2>
 <!-- ======================================================================= -->
 
-<p> Optional string message can be added to Deprecated and Available attributes. </p>
+<p>An optional string message can be added to the <tt>deprecated</tt>
+and <tt>unavailable</tt> attributes.  For example:</p>
+
+<blockquote>
+<pre>void explode(void) __attribute__((deprecated("extremely unsafe!!!")));</pre>
+</blockquote>
+
+<p>If the deprecated or unavailable declaration is used, the message
+will be incorporated into the appropriate diagnostic:</p>
+
+<blockquote>
+<pre>harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe!!! [-Wdeprecated-declarations]
+  explode();
+  ^</pre>
+</blockquote>
+
+<p>Query for this feature
+with <tt>__has_feature(attribute_deprecated_with_message)</tt>
+and <tt>__has_feature(attribute_unavailable_with_message)</tt>.</p>
+
+<!-- ======================================================================= -->
+<h2 id="attributes-on-enumerators">Attributes on Enumerators</h2>
+<!-- ======================================================================= -->
+
+<p>Clang allows attributes to be written on individual enumerators.
+This allows enumerators to be deprecated, made unavailable, etc.  The
+attribute must appear after the enumerator name and before any
+initializer, like so:</p>
+
+<blockquote>
+<pre>enum OperationMode {
+  OM_Invalid,
+  OM_Normal,
+  OM_Terrified __attribute__((deprecated)),
+  OM_AbortOnError __attribute__((deprecated)) = 4
+};</pre>
+</blockquote>
+
+<p>Attributes on the <tt>enum</tt> declaration do not apply to
+individual enumerators.</p>
 
-<p> Message will be added to deprecated warning or unavailable error if present. </p>
+<p>Query for this feature with <tt>__has_feature(enumerator_attributes)</tt>.</p>
 
 <!-- ======================================================================= -->
 <h2 id="checking_language_features">Checks for Standard Language Features</h2>
diff --git a/lib/Lex/PPMacroExpansion.cpp b/lib/Lex/PPMacroExpansion.cpp
index a9f4cacf6c..93532d19eb 100644
--- a/lib/Lex/PPMacroExpansion.cpp
+++ b/lib/Lex/PPMacroExpansion.cpp
@@ -521,11 +521,13 @@ static bool HasFeature(const Preprocessor &PP, const IdentifierInfo *II) {
            .Case("attribute_analyzer_noreturn", true)
            .Case("attribute_cf_returns_not_retained", true)
            .Case("attribute_cf_returns_retained", true)
+           .Case("attribute_deprecated_with_message", true)
            .Case("attribute_ext_vector_type", true)
            .Case("attribute_ns_returns_not_retained", true)
            .Case("attribute_ns_returns_retained", true)
            .Case("attribute_objc_ivar_unused", true)
            .Case("attribute_overloadable", true)
+           .Case("attribute_unavailable_with_message", true)
            .Case("blocks", LangOpts.Blocks)
            .Case("cxx_attributes", LangOpts.CPlusPlus0x)
            .Case("cxx_auto_type", LangOpts.CPlusPlus0x)
@@ -536,6 +538,7 @@ static bool HasFeature(const Preprocessor &PP, const IdentifierInfo *II) {
            .Case("cxx_strong_enums", LangOpts.CPlusPlus0x)
            .Case("cxx_static_assert", LangOpts.CPlusPlus0x)
            .Case("cxx_trailing_return", LangOpts.CPlusPlus0x)
+           .Case("enumerator_attributes", true)
            .Case("objc_nonfragile_abi", LangOpts.ObjCNonFragileABI)
            .Case("objc_weak_class", LangOpts.ObjCNonFragileABI)
            .Case("ownership_holds", true)
diff --git a/test/Sema/attr-deprecated.c b/test/Sema/attr-deprecated.c
index f9cdaf067c..b26171b86b 100644
--- a/test/Sema/attr-deprecated.c
+++ b/test/Sema/attr-deprecated.c
@@ -109,3 +109,5 @@ void test20() {
   f = test20_a; // expected-warning {{'test20_a' is deprecated}}
   f = test20_b;
 }
+
+char test21[__has_feature(attribute_deprecated_with_message) ? 1 : -1];
diff --git a/test/Sema/attr-unavailable-message.c b/test/Sema/attr-unavailable-message.c
index 4d07a238a9..a1e047c817 100644
--- a/test/Sema/attr-unavailable-message.c
+++ b/test/Sema/attr-unavailable-message.c
@@ -14,3 +14,5 @@ void test_foo() {
 
   double (*fp4)(double) = dfoo;  // expected-error {{'dfoo' is unavailable: NO LONGER}}
 }
+
+char test2[__has_feature(attribute_unavailable_with_message) ? 1 : -1];
diff --git a/test/Sema/enum.c b/test/Sema/enum.c
index 64aa31bc4b..d83b06f56b 100644
--- a/test/Sema/enum.c
+++ b/test/Sema/enum.c
@@ -102,3 +102,5 @@ extern enum PR7911T PR7911V; // expected-warning{{ISO C forbids forward referenc
 void PR7911F() {
   switch (PR7911V); // expected-error {{statement requires expression of integer type}}
 }
+
+char test5[__has_feature(enumerator_attributes) ? 1 : -1];