How do I flag a method as deprecated in Objective-C 2.0?

I'm part of a team developing a fairly large iPad app and there are many different classes we've created as a result. The trouble is some of the methods are now pretty much obsolete and I don't want simply remove them yet as I know some parts of the overall system use the methods... but there are better (newer) variants available which should be used instead (some of the old ones actually call the new ones, but the overall class interface is getting messy).

Is there a way in which I can mark certain methods as depreciated (like @deprecated in Java and [Obsolete] in .NET).

I see that Apple use Availability.h and have tags such as

__OSX_AVAILABLE_BUT_DEPRECATED(__MAC_NA,__MAC_NA,__IPHONE_2_0,__IPHONE_3_0);

... is this the only way to do it (+ is it App Store safe to do this?) or are there alternatives which will flag a warning in Xcode?

Deprecation Syntax

Syntax is provided to mark methods as deprecated:

@interface SomeClass
-method __attribute__((deprecated));
@end

or:

#include <AvailabilityMacros.h>
@interface SomeClass
-method DEPRECATED_ATTRIBUTE;  // or some other deployment-target-specific macro
@end

IMHO, it's easier to write __deprecated:

- (void)myDeprecatedMethod __deprecated;
- (int)methodNameDeprecated:(int)param __deprecated;

Works too on classes

__deprecated
@interface MyDeprecatedClass

  // ... some properties and methods ...

@end

If you want to give additional message with the deprecation flag, you can use following flags.

@property (strong, nonatomic) NSString *catName
                    __deprecated_msg("use name instead.");

//  -- Or -- 
@property (strong, nonatomic) NSString *catName
                    DEPRECATED_MSG_ATTRIBUTE("use name instead.");

//  -- Or -- 
@property (strong, nonatomic) NSString *catName
                    __attribute__((deprecated("use name instead.")));

Using above mentioned flags, you can tell why you are deprecating or what is the method developer should use in future.

Use the deprecated attribute:

- (int)bar: (int)x __attribute__((deprecated));

To mark a method as deprecated, use attribute((deprecated("Your message goes here")))

A practical example, from Mantle

@interface NSValueTransformer (UnavailableMTLPredefinedTransformerAdditions)

+ (NSValueTransformer *)mtl_externalRepresentationTransformerWithModelClass:(Class)modelClass __attribute__((deprecated("Replaced by +mtl_JSONDictionaryTransformerWithModelClass:")));
+ (NSValueTransformer *)mtl_externalRepresentationArrayTransformerWithModelClass:(Class)modelClass __attribute__((deprecated("Replaced by +mtl_JSONArrayTransformerWithModelClass:")));

@end