What are documentation comments in Xcode?

Question

This question is for reference purposes.

In the "Fonts & Colors" tab of the Settings window of Xcode, there's a setting for documentation comments (and keywords)? What are they?

Answer 1

Feel free to enhance this answer.

Documentation comments are just (Objective-C) comments marked as documentation. They are treated the same way as normal comments, except that you can set another color and font in Xcode. Some documentation software may even use these comments to create automatically documentation from given header files and other source code.

Documentation comment keywords are keywords that give semantical meaning to text that follows after the keyword in a documentation comment.

You can create inline documentation comments with three slashes (instead of two in normal comments), and block doc. comments with two stars instead of one (instead of one in normal comments). Example:

// Normal inline comment
/// Documentation comment

/* Normal block
comment */
/** Documentation block
comment */

You can create documentation comment keywords by specifying a keyword (one word only) after the "at" symbol. Example:

- (void)sendMessage: (id)sender;
/// @description Sends the receiver.
/// @available Version 1.0 through 2.2

Appledoc is a tool for creating a documentation set from your source code (including documentation comments and method signatures) and getting it to install and reload inside Xcode when needed. It's a command-line program and has instructions for how to incorporate it into your Xcode build process.

Once you have a documentation set you can add it to Xcode via Preferences > Downloads > Documentation.

The special keywords starting with an @-sign is also called HeaderDoc tags. A list of them can be found in the HeaderDoc User Guide. Please note that some of them are Objective-C and some are C++.

Answer 2

For those who did not watch the latest keynote: With Xcode 5 this feature will be built in. It is already available in the current developer preview (called quick help, like announced here).

Answer 3

Xcode 5 now has built-in support for DOxygen style comments. So, you can comment your methods like this:

/*!
 * Provides an NSManagedObjectContext singleton appropriate for use on the main 
 * thread. If the context doesn't already exist it is created and bound to the 
 * persistent store coordinator for the application, otherwise the existing 
 * singleton contextis returned.
 * \param someParameter You can even add parameters
 * \returns The a shared NSManagedObjectContext for the application.
 */
+ (NSManagedObjectContext *)sharedContext;

Inline help will look like this:

Quick help will look like this:

And sidebar help will look like this:

Here's a handy code snippet you can add the your Xcode Code Snippet library to make method documentation simple:

/**
 <#description#>
 @param <#parameter#>
 @returns <#retval#>
 @exception <#throws#>
 */

Now, you can just type "doxy" and poof! You have your doxygen template.

Answer 4

There are a number of tools such as Doxygen, Javadoc, and others which recognize "special" comments (known as documentation comments) to automatically generate documentation for the code.

Typically, documentation comments start with a special sequence such as /** (as opposed to just /*) and contain special keywords that often have a special start symbol such as @. There are a lot of similarities between the different comment documentation generators, most of which accept "@param" to document parameters, "@return" to document return values, "@throws" to document exceptions, etc.

In the context of Xcode's syntax highlighting, documentation comments are those with one of these special start sequences that Xcode happens to recognize. It should be noted that there a specific set of such comments that Xcode properly recognizes; for example, the Doxygen tool also allows /*! and //! (with an exclamation) to indicate the start of documentation comments, but Xcode doesn't recognize it.