KRStaticAnalyzerAnnotations.h - Source code notations for the clang static analyser

KRStaticAnalyzerAnnotations.h

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
///
///		KRStaticAnalyzerAnnotations.h
///
///		The Clang frontend supports several source-level annotations in the form of GCC-style attributes and pragmas 
///		that can help make using the Clang Static Analyzer more useful. These annotations can both help suppress
///		false positives as well as enhance the analyzer's ability to find bugs.
///
///		For more info see: http://clang-analyzer.llvm.org/annotations.html
///		
///		Copyright (c) Kevin Ross. All rights reserved.
///
///		Mutator:		Mutated:		Mutation:
///		--------		--------		---------
///		Kross			11.07.11		Initial Version
///
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////



#ifndef KRStaticAnalyzerAnnotations_h
#define KRStaticAnalyzerAnnotations_h

#ifndef __has_feature      // Optional.
#define __has_feature(x) 0 // Compatibility with non-clang compilers.
#endif

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
#pragma mark - Deprecated
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
#ifndef CLANG_DEPRECATED
#define CLANG_DEPRECATED __attribute__((deprecated))
#else
#define CLANG_DEPRECATED
#endif

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
#pragma mark - Null Pointer Checking
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

/**
 * Both the Clang compiler and GCC will flag warnings for simple cases where a null pointer is directly being passed
 * to a function with a 'nonnull' parameter (e.g., as a constant). The analyzer extends this checking by using 
 * its deeper symbolic analysis to track what pointer values are potentially null and then flag warnings
 * when they are passed in a function call via a 'nonnull' parameter.
 
 The nonnull attribute specifies that some function parameters should be non-null pointers. For instance, the declaration:
 extern void *
 my_memcpy (void *dest, const void *src, size_t len)
 __attribute__((nonnull (1, 2)));
 
 causes the compiler to check that, in calls to my_memcpy, arguments dest and src are non-null. If the compiler determines that a null pointer is passed in an argument slot marked as non-null, and the -Wnonnull option is enabled, a warning is issued. The compiler may also choose to make optimizations based on the knowledge that certain function arguments will not be null.
 
 If no argument index list is given to the nonnull attribute, all pointer arguments are marked as non-null. To illustrate, the following declaration is equivalent to the previous example:
 
 */


#ifndef CLANG_NOT_USED
#define CLANG_NOT_USED __attribute__((unused))
#else
#define CLANG_NOT_USED
#endif

#ifndef CLANG_NON_NULL
	#define CLANG_NON_NULL(argIndex, ...) __attribute__((nonnull (argIndex, ...)))
#else
	#define CLANG_NON_NULL
#endif



////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
#pragma mark - Objective-C Object Annotations
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////


#ifndef NS_RETURNS_RETAINED
	#if __has_feature(attribute_ns_returns_retained)
		#define NS_RETURNS_RETAINED __attribute__((ns_returns_retained))
	#else
		#define NS_RETURNS_RETAINED
	#endif
#endif

#ifndef NS_RETURNS_NOT_RETAINED
	#if __has_feature(attribute_ns_returns_not_retained)
		#define NS_RETURNS_NOT_RETAINED __attribute__((ns_returns_not_retained))
	#else
		#define NS_RETURNS_NOT_RETAINED
	#endif
#endif


#ifndef NS_CONSUMED
	#if __has_feature(attribute_ns_consumed)
		#define NS_CONSUMED __attribute__((ns_consumed))
	#else
		#define NS_CONSUMED
	#endif
#endif





////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
#pragma mark - Core Foundation Object Annotations
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////


#ifndef CF_RETURNS_RETAINED
	#if __has_feature(attribute_cf_returns_retained)
		#define CF_RETURNS_RETAINED __attribute__((cf_returns_retained))
	#else
		#define CF_RETURNS_RETAINED
	#endif
#endif


#ifndef CF_RETURNS_NOT_RETAINED
	#if __has_feature(attribute_cf_returns_not_retained)
		#define CF_RETURNS_NOT_RETAINED __attribute__((cf_returns_not_retained))
	#else
		#define CF_RETURNS_NOT_RETAINED
	#endif
#endif

#ifndef CF_CONSUMED
	#if __has_feature(attribute_cf_consumed)
		#define CF_CONSUMED __attribute__((cf_consumed))
	#else
		#define CF_CONSUMED
	#endif
#endif




#endif // KRStaticAnalyzerAnnotations_h