Documentation bugs in public iOS headers.

[GoogleCodeExporter]

What steps will reproduce the problem?
1.  In XCode 6.3   go to BuildSettings.
2.  Search for "Documentation Comments"  (its under "Apple LLVM 6.1 - Warnings 
- All languages")
3.  Turn warnings on.

What is the expected output? What do you see instead?

All the documentation comments should be correct and issue no warnings.  
Instead,  I see 8 warnings on version 2.6.0.  All warnings fall into one of two 
repeating patterns and are trivial to fix. 

Pattern #1 "Declaration is marked with \deprecated command but does not have a 
deprecation attribute."

Example: (from GCKDeviceManager.h)
"""
/**
 * True if the device manager has established a connection to the device.
 *
 * @deprecated Use @link connectionState @endlink.
 */
@property(nonatomic, readonly) BOOL isConnected;
"""

FIX:  make the code consistent with the documentation comment by adding the 
matching LLVM directive.
"""
@property(nonatomic, readonly) BOOL isConnected __attribute__((deprecated));
"""

Pattern #2:  Parameter '<something>' not found in the function declaration
Example (again from GCKDeviceManager.h)
"""
/**
 * Called whenever the application metadata for the currently running application has changed.
 *
 * @param applicationMetadata The application metadata. May be nil if no application is currently
 * running.
 */
- (void)deviceManager:(GCKDeviceManager *)deviceManager
    didReceiveApplicationMetadata:(GCKApplicationMetadata *)metadata;
"""

FIX:   Note that the @param tag in the doc comment is "applicationMetadata" 
which does not match the name of the actual variable (in this case, just 
"metadata".   This is probably a case of API drift and the documentation 
becoming out of sync.

What version of the product are you using? On what operating system?

This is a documentation bug, not a runtime bug.  This does become a problem for 
projects with "zero warning" policies for mainline commits.

Please provide any additional information below.

Original issue reported on code.google.com by g...@clasp.tv on 10 Apr 2015 at 5:36

[GoogleCodeExporter]

P.S.  AvailabilityMacros.h   has some #defines to make the syntax more 
palatable.

#define DEPRECATED_ATTRIBUTE        __attribute__((deprecated))
#define DEPRECATED_MSG_ATTRIBUTE(msg) __attribute((deprecated((msg))))

Original comment by g...@clasp.tv on 10 Apr 2015 at 5:49

[GoogleCodeExporter]

Thank you for reporting the issue. It is being investigated, tracker will be 
updated accordingly.  

Original comment by na...@google.com on 10 Apr 2015 at 10:14

• Changed state: Acknowledged