Documenting your code with comments in Xcode 5

One of the nice new features introduced in Xcode 5 is the ability for source code comments to be used as documentation displayed in the Quick Help Inspector, in a Help Popup, and for Code Completion. I believe that this is made possible because Xcode now uses exclusively Apple’s own LLVM 5 compiler (GCC support has been removed), so it can build this functionality right in, since the compiler processes the comments along with user code. This kind of feature has long been available for users of other IDEs, such as Eclipse, and so this is a very welcome addition to Xcode, particularly as it might encourage developers to better document their code.

You can use either Doxygen or HeaderDoc format for the comments. As I come from a Java background I like to make the comments as close to JavaDoc as possible.

Here’s a simple example. This is a declaration for a utility method to check whether a file at a given URL has a newer time-stamp than another file at a given URL:

/**
 Check whether a file at a given URL has a newer timestamp than a given file.
 Example usage:
 @code
 NSURL *url1, *url2;
 BOOL isNewer = [FileUtils
         isThisFileNewerThanThatFile:url1 thatURL:url2];
 @endcode
 @see https://www.dadabeatnik.com for more information.
 @param thisURL
        The URL of the source file.
 @param thatURL
        The URL of the target file to check.
 @return YES if the timestamp of @c thatURL is newer than the timestamp of @c thisURL,
         otherwise NO.
 */
+ (BOOL)isThisFileNewerThanThatFile:(NSURL *)thisURL thatURL:(NSURL *)thatURL;

In my configuration of Xcode it looks like this:

The comments sit right on top of the method declaration in the header file. There’s no point in putting them in the matching implementation file as we need these comments to be part of the public API.

The comment opens with a /** block start and ends with a final */ block end. After the block start I’ve added a general description about what the method does. Then I’ve opened a @code tag and provided some code for example usage (this is a bit like the <pre> HTML tag). The @endcode tag closes it. Then I’ve added a @see tag which will appear as “See Also”. After this are the important tags used to document the two parameters and the return value. These are @param and @return. Note the @c tags in the “Returns” description which serve to display the following word using a monospaced font.

Note that it’s important to save your source file in order for Xcode to detect a change to the file and regenerate the documentation from the comments.

Now that this is done, if we select the method in the editor either here in the declaration, or as implemented, and then Option-Click on it we get the Help popup:

And it will also display in the Help Inspector:

And also will appear for Code Completion:

As a bonus, if we want to ensure that we get the spelling of the names of the parameters right, there’s even a project setting built into Xcode that will check and warn us:

Now, if I create a typo in the documentation I see this:

Clicking on the yellow triangle leads to a very helpful suggestion:

And that’s about it. A very nice and welcome addition to Xcode. Now that Apple is focussed on only supporting its own LLVM compiler in Xcode, I hope we’ll see more of these types of features in future versions.