1717< h1 > Source Annotations</ h1 >
1818
1919< p > The Clang frontend supports several source-level annotations in the form of
20- < a href ="http ://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html "> GCC-style
20+ < a href ="https ://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html "> GCC-style
2121attributes</ a > and pragmas that can help make using the Clang Static Analyzer
2222more useful. These annotations can both help suppress false positives as well as
2323enhance the analyzer's ability to find bugs.</ p >
2424
2525< p > This page gives a practical overview of such annotations. For more technical
2626specifics regarding Clang-specific annotations please see the Clang's list of < a
27- href ="http ://clang.llvm.org/docs/LanguageExtensions.html "> language
27+ href ="https ://clang.llvm.org/docs/LanguageExtensions.html "> language
2828extensions</ a > . Details of "standard" GCC attributes (that Clang also
29- supports) can be found in the < a href ="http ://gcc.gnu.org/onlinedocs/gcc/ "> GCC
29+ supports) can be found in the < a href ="https ://gcc.gnu.org/onlinedocs/gcc/ "> GCC
3030manual</ a > , with the majority of the relevant attributes being in the section on
31- < a href ="http ://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html "> function
31+ < a href ="https ://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html "> function
3232attributes</ a > .</ p >
3333
3434< p > Note that attributes that are labeled < b > Clang-specific</ b > are not
@@ -68,7 +68,7 @@ <h4>Specific Topics</h4>
6868 < li > < a href ="#attr_os_consumes_this "> Attribute 'os_consumes_this'</ a > </ li >
6969 < li > < a href ="#os_out_parameters "> Out Parameters</ a > </ li >
7070 </ ul >
71-
71+
7272 </ li >
7373 </ ul >
7474</ li >
@@ -91,7 +91,7 @@ <h4 id="attr_nonnull">Attribute 'nonnull'</h4>
9191< p > The analyzer recognizes the GCC attribute 'nonnull', which indicates that a
9292function expects that a given function parameter is not a null pointer. Specific
9393details of the syntax of using the 'nonnull' attribute can be found in < a
94- href ="http ://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html#index-g_t_0040code_007bnonnull_007d -function-attribute-2263 "> GCC's
94+ href ="https ://gcc.gnu.org/onlinedocs/gcc/Common- Function-Attributes.html#index-nonnull -function-attribute "> GCC's
9595documentation</ a > .</ p >
9696
9797< p > Both the Clang compiler and GCC will flag warnings for simple cases where a
@@ -108,7 +108,7 @@ <h4 id="attr_nonnull">Attribute 'nonnull'</h4>
108108int bar(int*p, int q, int *r) __attribute__((nonnull(1,3)));
109109
110110int foo(int *p, int *q) {
111- return !p ? bar(q, 2, p)
111+ return !p ? bar(q, 2, p)
112112 : bar(p, 2, q);
113113}
114114</ pre >
@@ -138,8 +138,8 @@ <h3 id="cocoa_mem">Cocoa & Core Foundation Memory Management
138138< p > One can educate the analyzer (and others who read your code) about methods or
139139functions that deviate from the Cocoa and Core Foundation conventions using the
140140attributes described here. However, you should consider using proper naming
141- conventions or the < a
142- href ="http ://clang.llvm.org/docs/LanguageExtensions.html#the-objc-method-family-attribute "> < tt > objc_method_family</ tt > </ a >
141+ conventions or the < a
142+ href ="https ://clang.llvm.org/docs/LanguageExtensions.html#the-objc-method-family-attribute "> < tt > objc_method_family</ tt > </ a >
143143attribute, if applicable.</ p >
144144
145145< h4 id ="attr_ns_returns_retained "> Attribute 'ns_returns_retained'
@@ -236,7 +236,7 @@ <h4 id="attr_cf_returns_retained">Attribute 'cf_returns_retained'
236236
237237< p > The GCC-style (Clang-specific) attribute 'cf_returns_retained' allows one to
238238annotate an Objective-C method or C function as returning a retained Core
239- Foundation object that the caller is responsible for releasing. The
239+ Foundation object that the caller is responsible for releasing. The
240240CoreFoundation framework defines a macro < b > < tt > CF_RETURNS_RETAINED</ tt > </ b >
241241that is functionally equivalent to the one shown below.</ p >
242242
@@ -323,7 +323,7 @@ <h4 id="attr_cf_returns_not_retained">Attribute 'cf_returns_not_retained'
323323method may appear to obey the Core Foundation or Cocoa conventions and return
324324a retained Core Foundation object, this attribute can be used to indicate that
325325the object reference returned should not be considered as an
326- "owning" reference being returned to the caller. The
326+ "owning" reference being returned to the caller. The
327327CoreFoundation framework defines a macro < b > < tt > CF_RETURNS_NOT_RETAINED</ tt > </ b >
328328that is functionally equivalent to the one shown below.</ p >
329329
@@ -353,8 +353,8 @@ <h4 id="attr_ns_consumed">Attribute 'ns_consumed'
353353< p > The 'ns_consumed' attribute can be placed on a specific parameter in either
354354the declaration of a function or an Objective-C method. It indicates to the
355355static analyzer that a < tt > release</ tt > message is implicitly sent to the
356- parameter upon completion of the call to the given function or method. The
357- Foundation framework defines a macro < b > < tt > NS_RELEASES_ARGUMENT</ tt > </ b > that
356+ parameter upon completion of the call to the given function or method. The
357+ Foundation framework defines a macro < b > < tt > NS_RELEASES_ARGUMENT</ tt > </ b > that
358358is functionally equivalent to the < tt > NS_CONSUMED</ tt > macro shown below.</ p >
359359
360360< p > < b > Example</ b > </ p >
@@ -408,7 +408,7 @@ <h4 id="attr_cf_consumed">Attribute 'cf_consumed'
408408to the given function or method. The CoreFoundation framework defines a macro
409409< b > < tt > CF_RELEASES_ARGUMENT</ tt > </ b > that is functionally equivalent to the
410410< tt > CF_CONSUMED</ tt > macro shown below.</ p >
411-
411+
412412< p > Operationally this attribute is nearly identical to 'ns_consumed'.</ p >
413413
414414< p > < b > Example</ b > </ p >
@@ -438,7 +438,7 @@ <h4 id="attr_cf_consumed">Attribute 'cf_consumed'
438438void test2() {
439439 CFDateRef date = CFDateCreate(0, CFAbsoluteTimeGetCurrent());
440440 consume_CFDate(date); < b > < i > // No leak, including under GC!</ i > </ b >
441-
441+
442442}
443443
444444@interface Foo : NSObject
@@ -463,7 +463,7 @@ <h4 id="attr_ns_consumes_self">Attribute 'ns_consumes_self'
463463follow the standard Cocoa naming conventions.</ p >
464464
465465< p > < b > Example</ b > </ p >
466-
466+
467467< pre class ="code_example ">
468468#ifndef __has_feature
469469#define __has_feature(x) 0 // Compatibility with non-clang compilers.
@@ -573,8 +573,8 @@ <h5>Example</h5>
573573 OSObject *f;
574574 LIBKERN_RETURNS_NOT_RETAINED OSObject *myFieldGetter();
575575}
576-
577-
576+
577+
578578// Note that the annotation only has to be applied to the function declaration.
579579OSObject * MyClass::myFieldGetter() {
580580 return f;
@@ -633,7 +633,7 @@ <h4 id="os_out_parameters">Out Parameters</h4>
633633void getterViaOutParam(LIBKERN_RETURNS_NOT_RETAINED OSObject **obj)
634634</ pre >
635635< p >
636- In such cases a retained object is written into an out parameter, which the caller has then to release in order to avoid a leak.
636+ In such cases a retained object is written into an out parameter, which the caller has then to release in order to avoid a leak.
637637</ p >
638638
639639< p > These two cases are simple - but in practice a functions returning an out-parameter usually also return a return code, and then an out parameter may or may not be written, which conditionally depends on the exit code, e.g.:</ p >
@@ -718,7 +718,7 @@ <h2 id="custom_assertions">Custom Assertion Handlers</h2>
718718< p > The analyzer knows about several well-known assertion handlers, but can
719719automatically infer if a function should be treated as an assertion handler if
720720it is annotated with the 'noreturn' attribute or the (Clang-specific)
721- 'analyzer_noreturn' attribute. Note that, currently, clang does not support
721+ 'analyzer_noreturn' attribute. Note that, currently, clang does not support
722722these attributes on Objective-C methods and C++ methods.</ p >
723723
724724< h4 id ="attr_noreturn "> Attribute 'noreturn'</ h4 >
@@ -729,7 +729,7 @@ <h4 id="attr_noreturn">Attribute 'noreturn'</h4>
729729
730730< p > Specific details of the syntax of using the 'noreturn' attribute can be found
731731in < a
732- href ="http ://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html#index-g_t_0040code_007bnoreturn_007d -function-attribute-2264 "> GCC's
732+ href ="https ://gcc.gnu.org/onlinedocs/gcc/Common- Function-Attributes.html#index-noreturn -function-attribute "> GCC's
733733documentation</ a > .</ p >
734734
735735< p > Not only does the analyzer exploit this information when pruning false paths,
0 commit comments