Question

I find documentating my interfaces particularly painful because I need to type everything myself. So I figured that I must not be the only one like this and started to look for a way to reduce my pain but didn’t find much.

My question is, is there a shortcut or a way to have Xcode autocomplete my comments? For example, I’d very much like if I type /** + [tab] that it autocompletes to:

/**
 * [cursor here]
 * 
 * (maybe some pre-populate a list of arguments for the method below)
 */
- (void)test:(NSString *)testString another:(NSString *)another;

Thanks!

Answer 1

Use Xcode’s snippets feature. You can create a snippet with whatever text you want, and add items in the text to be filled in. To create a snippet, just select some text in an Xcode editor and drag it into the snippet library. You can set the completion shortcut, so something like m-comment could be your standard method comment:

Typing the first bit of m-comment then displays the entire shortcut (and any other completions), and accepting the completion adds a comment with the parameterized parts waiting to be filled in. As usual, you can tab from one to the next:

You indicate that a given part of the text is a field to be filled in by enclosing it in <# and #>, like: <#method name#>.

Of course, one of the strengths of Objective-C is that the method name generally tells you what the parameters are. Repeating that in a comment seems like unnecessary extra work. Xcode 3 had better support for scripts included scripts that would automatically generate HeaderDoc comments with parameters. They weren’t widely used, though, probably because those kinds of comments weren’t really useful.