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:

In my configuration of Xcode it looks like this:

Xcode method

Xcode method with comments

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:

Xcode Help Popup

Xcode Help Popup

And it will also display in the Help Inspector:

Xcode Help Inspector

Xcode Help Inspector

And also will appear for Code Completion:

Code Completion

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:

Xcode Settings

Xcode Documentation Comments Settings

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

Xcode Warning

Xcode typo warning

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

Xcode Assist

Xcode Assist

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.

Share this...Tweet about this on TwitterShare on LinkedInShare on Facebook

6 thoughts on “Documenting your code with comments in Xcode 5

  1. Thanks for pointing this out. Nice write-up. However, it is not a feature that requires clang. It works even for plug-ins that utilize other compilers.

Comments are closed.