This is a hint for ARC to know that the returned object will need to be released at some point.

Stepan, is that correct?

I recall Stepan telling that ARC annotations are not doing anything for C++ methods. Did I make this up? :)

ARC annotation works, except maybe NS_CONSUMED on a C++ class constructor (this is a bug in clang, maybe fixed with the ToT version but not yet in the version shipped with clang).

The possible annotation are detailed in https://clang-analyzer.llvm.org/annotations.html.

NS_RETURNS_RETAINED means that the function/method returns an object with a reference owned by the caller (this should be used only when the function/method does not respect the memory management policy naming convention https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmRules.html).

In general, it is better to return base::scoped_nsobject<Foo> though until both caller and callee have been converted to ARC, as not using the correct annotation can lead over retain or over release if the annotation does not match how the code is written.