Index: cfe/trunk/www/analyzer/annotations.html =================================================================== --- cfe/trunk/www/analyzer/annotations.html +++ cfe/trunk/www/analyzer/annotations.html @@ -152,16 +152,6 @@ is returned retained. Explicitly adding the 'ns_returns_retained' attribute to C functions allows the analyzer to perform extra checking.

-

Important note when using Garbage Collection: Note that the analyzer -interprets this attribute slightly differently when using Objective-C garbage -collection (available on Mac OS 10.5+). When analyzing Cocoa code that uses -garbage collection, "alloc" methods are assumed to return an object -that is managed by the garbage collector (and thus doesn't have a retain count -the caller must balance). These same assumptions are applied to methods or -functions annotated with 'ns_returns_retained'. If you are returning a Core -Foundation object (which may not be managed by the garbage collector) you should -use 'cf_returns_retained'.

-

Example

@@ -243,16 +233,15 @@
 

Placing on Objective-C methods: With respect to Objective-C methods., this attribute is identical in its behavior and usage to 'ns_returns_retained' except for the distinction of returning a Core Foundation object instead of a -Cocoa object. This distinction is important for two reasons:

+Cocoa object. - +This distinction is important for the following reason: +as Core Foundation is a C API, +the analyzer cannot always tell that a pointer return value refers to a +Core Foundation object. +In contrast, it is +trivial for the analyzer to recognize if a pointer refers to a Cocoa object +(given the Objective-C type system).

Placing on C functions: When placing the attribute 'cf_returns_retained' on the declarations of C functions, the analyzer @@ -264,17 +253,11 @@ contained the keywords "create" or "copy". This means the returned object as a +1 retain count that must be released by the caller, either by sending a release message (via toll-free bridging to an Objective-C -object pointer), calling CFRelease (or similar function), or using -CFMakeCollectable to register the object with the Objective-C garbage -collector. +object pointer), or calling CFRelease or a similar function.

Example

-

In this example, observe the difference in output when the code is compiled -to not use garbage collection versus when it is compiled to only use garbage -collection (-fobjc-gc-only).

-
 $ cat test.m
 $ cat test.m
@@ -322,15 +305,6 @@
 
 example returns retained
 
-

When the above code is compiled using Objective-C garbage collection (i.e., -code is compiled with the flag -fobjc-gc or -fobjc-gc-only), -scan-build produces both the above error (with slightly different text -to indicate the code uses garbage collection) as well as the following warning, -which indicates a leak that occurs only when using garbage -collection:

- -example returns retained gc -

Attribute 'cf_returns_not_retained' (Clang-specific)

@@ -372,13 +346,6 @@ parameter upon completion of the call to the given function or method. The Foundation framework defines a macro NS_RELEASES_ARGUMENT that is functionally equivalent to the NS_CONSUMED macro shown below.

- -

Important note when using Garbage Collection: Note that the analyzer -essentially ignores this attribute when code is compiled to use Objective-C -garbage collection. This is because the release message does nothing -when using GC. If the underlying function/method uses something like -CFRelease to decrement the reference count, consider using -the cf_consumed attribute instead.

Example

@@ -432,10 +399,7 @@ CF_RELEASES_ARGUMENT that is functionally equivalent to the CF_CONSUMED macro shown below.

-

Operationally this attribute is nearly identical to 'ns_consumed' with the -main difference that the reference count decrement still occurs when using -Objective-C garbage collection (which is important for Core Foundation types, -which are not automatically garbage collected).

+

Operationally this attribute is nearly identical to 'ns_consumed'.

Example