The Confusatory

Welcome to 2016! If you’re writing Swift code, good news! Swift supports Markdown, so read up at NSHipster about the basics and enjoy your new markup!

What’s New in Xcode 5.0 contains a very short mention of some very fantastic documentation generation that’s been added to the IDE:

Project documentation from framework API reference documentation and structured comments in your own source code are displayed in the quick help panel and in code completion popover views. Doxygen and HeaderDoc structured comments are supported formats.

Doxygen’s documentation contains many, many examples of the multitude of ways to document your code, but here’s a simple version that’s easy to comprehend at a glance:

/**
 * Add a data point to the data source.
 * (Removes the oldest data point if the data source contains kMaxDataPoints objects.)
 *
 * @param aDataPoint An instance of ABCDataPoint.
 * @return The oldest data point, if any.
 */
 - (ABCDataPoint *)addDataToDataSource:(ABCDataPoint *)aDataPoint;

This renders in Xcode as:

(Don’t worry about the mismatch between the code above and my actual declaration from the screenshot, this is merely illustrative.)

My personal favorite, though, is how incredibly, fantastically, amazingly simple and easy it is to add documentation to a property:

/// Base64-encoded data.
@property (nonatomic, strong) NSData *data;

When option-clicked, this lovely popover appears:

If you’ve been practicing good documentation and already had comments above your properties, you’re in luck:

// This property stores the name of a user.

You can add that comment to the option-click documentation by adding a single forward slash to that comment. How great is that?!

2013-10-09: Matt Stevens points out -Wdocumentation, which is new in clang 3.2. From the Clang release notes:

… Clang parses the comments and can detect syntactic and semantic errors in comments. These warnings are off by default. Pass -Wdocumentation flag to enable warnings about documentation comments.

This will warn when the documentation’s variable names or return types don’t match the method signature.

Notes:

Xcode’s documentation appears to bind to the first declaration of a method. If you’ve not DRY-ed out your code when Xcode 4.3 made forward-declarations of methods optional, that means you’ll want to add your documentation to your forward declared method, not your actual implementation.

More information about Xcode’s DRY improvements coming soon.