Method 'documentation'

Question

What is the objective-c syntax for documenting a method's usage? Is this done in the .h or .m file?

In C# one uses something like:

/// <summary>
/// Executes an HTTP GET command and retrieves the information.     
/// </summary>
/// <param name="url">The URL to perform the GET operation</param>
/// <param name="userName">The username to use with the request</param>
/// <param name="password">The password to use with the request</param>
/// <returns>The response of the request, or null if we got 404 or nothing.</returns>
protected string ExecuteGetCommand(string url, string userName, string password) {
...
}

Is this done with the #pragma directive?

Thanks,

Craig Buchanan

Answer 1

There's a new ability in Xcode 5 to document your methods. In your header file, you can add comments to your function like so to make them show up in documentation:

/*! Executes an HTTP GET command and retrieves the information.
 * \param url The URL to perform the GET operation
 * \param userName The username to use with the request
 * \param password The password to use with the request
 * \returns The response of the request, or null if we got 404 or nothing
 */
- (NSString *)executeGetCommandWithURL:(NSURL *)url userName:(NSString *)aUserName andPassword:(NSString *)aPassword;

Note the exclamation point on the first line.

This documentation will show up in the Quick Help in the right pane of Xcode, and the description will show up in function auto-completion when you type.

Answer 2

Objective-C doesn't have a built-in documentation feature. Apple includes a tool called Headerdoc that can generate docs from source files, but there are several better options. I think the most popular is Doxygen, in which case the syntax is the Java-style /** Documentation here */. You can check out the Wikipedia page for examples of how it's used (albeit with other languages). Apple has instructions for using Doxygen with Xcode on its site.