You know this super helpful feature that displays pop-up help windows in Xcode? The one I always forget is there? CMD-Hover over a method you’re calling and something like the above window is displayed. For Apple’s own code it even features links to the documentation.
We can do this in our own code as well using Doxygen style comments. Just above your own methods, add the following comment style block:
* Elaborate description of your method
* Could be multiple lines, but they will be ignored.
* @brief Brief summary goes here
* @author Jay Versluis
* @param NSString takes first funky parameter
* @param NSNumber and another one
* @return returns complicated calculation
* @since Version 1.2
Now CMD-Hover over this method and that lovely box is displayed – it works anywhere you call it, even in different classes. This makes it a really useful feature, especially when you’ve forgotten how and why you’ve constructed code several moths down the line.
The parameters in those comments don’t need to be in order, Xcode will parse them no matter if @brief is at the top or @author is at the bottom. Empty lines don’t matter either, but they’re easier on the eyes.
The whole block is enclosed in standard /* multiline */ comments. The asterisks at the beginning of each line are not necessary either. Add one of the @ short codes on a new line, followed by your definitions. Some of the helpful ones are:
- @brief – optional summary
- @author – the author of the function, great for collaborative code (optional)
- @param – input parameter (the first word right after is assumed to be the type)
- @since – since which version this method is available (optional)
- @code and @endcode – give a brief usage example that’s formatted as a code block (optional)
- @see – adds a bold formatted “See Also” comment (optional)
I’m sure there are others, but I haven’t found any Apple documentation on those yet. Explore and document!
And check out Phil Beauvoir’s article for more tips on how to make this work for code completion: http://dadabeatnik.wordpress.com/2013/09/25/comment-docs-in-xcode-5/
This is one of those features that I wish Apple would tell you about. Perhaps in their… what’s it called.. documentation?