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:
Activate the right-hand Utilities drawer and in the bottom of it, click on the curly braces {} to activate the Code Snippet Library.
- In the code editor, type or paste the code that you want to turn into a snippet; highlight it all.
- 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.)
- 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.
- 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#> */
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.
Man I want my black belt in geek! Thanks for the post!
Pingback: Custom NSLog for Xcode 4 at avp::ptr weblog
Pingback: Documenting Objective-C Code | Mobile Product Development
Pingback: Xcode4, “code snippets” 기능으로 Doxygen 주석 쉽게 달기. « Lum7671's Weblog
Thank you very much 🙂
This is what I searched for 2 days!
wow, thank you!
@returns or @return ?
Pingback: Adding Documentation – appledoc | Thought Repository