Documenting in Xcode with HeaderDoc Tutorial

Making Your Life Easier: Code Snippets

That was really fast, no? But what if you could make that process faster?

There’s something that’s been mentioned before on the site, and on the the raywenderlich.com podcast: code snippets.

Code snippets are one of the unsung heroes of Xcode. A snippet is a block of code that you can save, to a snippet library, and reuse over and over again. Snippets can even contain placeholders for you to know what you need to fill in. What’s that you say? You want a snippet for documenting your code? Fabulous idea.

In MathAPI.h, copy and paste in the following, just before the comment you already have:

/*!
 * @discussion <#description#>
 * @param <#param description#>
 * @return <#return description#>
 */

Notice that when you copied or wrote out the code, the parts that had “” around them became tokens that you could tab between. It’s exactly the same thing when you use autocomplete for your code.

The next part may be a little tricky. You’ll need to select the Code Snippet Library in the Utilities panel, highlight your comment block, and drag the text to the Code Snippet Library section (by dragging from one of the placeholder text areas like ):

A popover will appear that lets you edit some information about the snippet and create an autocompletion shortcut. It will even let you edit the code. Fill out the information as you see it below:

If you ever need to change the code or autocomplete shortcut, you can always go back and do it later. Feel free to change it however you’d like, or make new ones. To edit the snippet, click on it in the Code Snippet Library, then click the Edit button.

To see your new snippet in action, delete the comments you added for addNumber:toNumber:, place your cursor to the left of the “+”, type doccomment, and hit enter. Your snippet text will appear.

Tab through the three tokens filling out each one to complete your documentation as follows:

/*!
 * @discussion A really simple way to calculate the sum of two numbers.
 * @param firstNumber An NSInteger to be used in the summation of two numbers.
 * @param secondNumber The second half of the equation.
 * @warning Please make note that this method is only good for adding non-negative numbers.
 * @return The sum of the two numbers passed in.
 */

Note you’ll need to still manually add a second @param tag and the @warning tag, but this snippet still saves a ton of time.

You’re doing great so far. See, this documentation stuff isn’t so bad after all!

Documenting Typedefs

Open Car.h. You’ll see there are a few more things here than the previous class. There’s an NS_ENUM, typedef enum, a block, multiple properties, and a void method. Don’t freak out – it’s still really easy to document a class with more than one or two things in it. :]

Remember the @typdef tag? This Top-Level tag is a little special. It can be used to document things like enum typedefs and struct typedefs. But depending on what you are documenting, it should only contain Second-Level tags that match the type being defined.

For enum, you’ll want to include the @constant tag for each constant you have. (For struct, you would include @field tags.)

Find the enum OldCarType. It has two constants, and these should always be really old cars. Above the typedef declaration, replace the existing comment so that it looks like this:

/*!
 * @typedef OldCarType
 * @brief A list of older car types.
 * @constant OldCarTypeModelT A cool old car.
 * @constant OldCarTypeModelA A sophisticated old car.
 */
typedef enum {
    OldCarTypeModelT,
    OldCarTypeModelA
} OldCarType;

Build, and option+click on OldCarType. You’ll notice your popover has the information from your @brief tag. Now, option+click on OldCarTypeModelA. Did you see your comment? Queue the sad music. :[

But fear not, you can still get your information where you need it – we’ve got the trusty triple forward slash in our tool belt. Add the comments to the enum like you see here:

typedef enum {
    /// A cool, old car.
    OldCarTypeModelT,
    /// A sophisticated older car.
    OldCarTypeModelA
} OldCarType;

When you build, and option+click, you’ll now see your comment.

Since there’s an NS_ENUM in the class, go head try documenting it on your own. The constants are already documented, it just needs to be commented overall.

[spoiler title=”Solution”]

/*!
 * @typedef CarType
 * @brief A list of newer car types.
 * @constant CarTypeHatchback Hatchbacks are fun, but small.
 * @constant CarTypeSedan Sedans should have enough room to put your kids, and your golf clubs
 * @constant CarTypeEstate Estate cars should hold your kids, groceries, sport equipment, etc.
 * @constant CarTypeSport Sport cars should be fast, fun, and hard on the back.
*/

[/spoiler]

Note: Since this enum is created through a macro, sadly Xcode doesn’t actually give you the same documentation features as a traditional typedef enum, even though NS_ENUM is the recommended way to make enums. Perhaps one day this will change, but for now, that’s the way it is.

Now take a minute to document the carType property. Add the following line above it’s declaration, so it looks like this:

/// Indicates the kind of car as enumerated in the "CarType" NS_ENUM
@property (nonatomic, assign) CarType carType;

Build again and then view your shorthand documentation by option-clicking the carType variable name.

Moving on, there’s also a typedef block in Car.h. Commenting a block is no more difficult than anything you’ve done so far. Add the text below so it looks like this:

/*!
 * @brief A block that makes the car drive.
 * @param distance The distance is equal to a distance driven when the block is ready to execute. It could be miles, or kilometers, but not both. Just pick one and stick with it. ;]
 */
typedef void(^driveCompletion)(CGFloat distance);

Notice that it’s not too different from anything else. It has:

• A @brief tag, giving a very simple explanation about the block.
• A @param tag, to let you know that you’ll need to pass something as a parameter when you call the block