Easy Doxygen code snippets for Xcode 4

Fred McCann has two great blog posts describing how to document  your Objective-C code with Doxygen, a popular and standardized documentation system for C, Java and other languages. His posts are extremely well-written and definitely worth a read; he takes you all the way from a basic introduction to Doxygen to generating the Doxyfile output.

But in Xcode 4 you don’t need to use a complicated scripting system to produce commonly-used Doxygen-compatible documentation. Xcode has a “snippets” facility that comes pre-populated with a variety of Objective-C snippets; let me show you how to leverage them.

Simple Doxygen documentation for a method might look something like this:

/**
Compute the distance to another waypoint in nm.
@param other the other Waypoint
@returns the distance in nm
*/

Why type all that over and over again? (And this is only a small subset of what Doxygen can do. In truth, the Doxygen system is very rich and, frankly, as complicated as you want to make it. Note that in this post I’m not covering Doxygen itself, just creating the code snippets.)

In Xcode 4 I use “dox <TAB>” to insert my custom method-documentation snippet. Here’s how you can do the same:

1. Activate the right-hand Utilities drawer and in the bottom of it, click on the curly braces {} to activate the Code Snippet Library.
2. In the code editor, type or paste the code that you want to turn into a snippet; highlight it all.
3. Drag the highlighted code to the Snippet library. (It can be stubborn and not want to drag. Holding the mouse button down for a moment before dragging seems to help.)
4. Your snippet has been added to the Library; click once on the snippet and a callout window will show you the snippet and permit you to edit it.
5. Add your own descripton, completion shortcut, etc. Any text you surround with <# #> marks will be highlighted with a blue bubble for quick tabbing and substitution.

Here’s the full snippet that I employ. It’s fast and it encourages proper code documentation.

/**
 <#description#>
 @param <#parameter#>
 @returns <#retval#>
 @exception <#throws#>
 */

Advertisements