27

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?

Improve this question
3
  • 2
    "This question has been asked before." So 2011 > 2013? :-p Commented Jul 29, 2014 at 11:55
  • 2
    Randy, there is a discussion about that here if you're curious. Commented Jul 29, 2014 at 13:10
  • The linked dupe is actually a different question. This asks what a doc comment is, and that asks what commands you can put in it. That assumes you already know what one is, and this isn't worried about commands. Commented Mar 11, 2015 at 17:36

4 Answers 4

Reset to default
47

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++.

Improve this answer
Sign up to request clarification or add additional context in comments.

4 Comments

I tried all these techniques and still can't get XCode 4.6 to show my comments during an option-hover (i.e. hold down alt, move mouse over method name, cursor changes to a ?, click). It says where it's declared, but nothing else. Am I doing something wrong or does XCode just not support doc comments?
@AlexChaffee: Xcode doesn't have this feature I'm afraid. I wish it had though. :-( The documentation comments are only for other tools to use this, not Apple's…
From Xcode 5, you can use Doxygen style comment to make documentation inside of Xcode tool. Please see my blog article about it
@Wonil That's indeed a nice feature now, yet I find both the syntax and the tool ugly. I'm not planning to use it any time soon, but for others it can be interesting.
43

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).

Code hint example

Improve this answer

2 Comments

actually XCode5 will simply parse any doxygen or headerdoc like comment. Meaning you can also use @param for example
Beautiful, I've been pining for this functionality for a long while.
14

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:

inline help



Quick help will look like this:

quick help



And sidebar help will look like this:

sidebar help

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#>
 */

doxygen code snippet

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

Improve this answer

Comments

7

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.

Improve this answer

2 Comments

Why bother to edit my answer clearly marked as a community wiki which has basically all the information you just gave?
@Randy, didn't realize it was a community wiki.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.