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:

 Read the rest of this story...

  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#>
 */
About these ads

9 thoughts on “Easy Doxygen code snippets for Xcode 4

  1. Good stuff, thanks! I had been using Fred McCann’s stuff in Xcode 3, but couldn’t get it working for XCode 4. This is great, especially since I can customize it exactly the way I want it.

  2. Pingback: Custom NSLog for Xcode 4 at avp::ptr weblog

  3. Pingback: Documenting Objective-C Code | Mobile Product Development

  4. Pingback: Xcode4, “code snippets” 기능으로 Doxygen 주석 쉽게 달기. « Lum7671's Weblog

  5. Pingback: Adding Documentation – appledoc | Thought Repository

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s