Resources‎ > ‎

HeaderDoc Reference by Justin Loew

Update: Ignore the rest of this page for now, it wasn't finished anyway. Apple has plenty of example code here that should give you a good idea of how to use HeaderDoc.

This document is a work in progress. It's mostly accurate, but there are a few holes.

HeaderDoc is a system for code documentation. When you annotate your code in the HeaderDoc format, Xcode will add your description to its function autocompletion suggestions and to the Quick Help pop-up. Just option-click on a variable or function, and Xcode will tell you what it does and where it comes from, just like with Apple's code.
Popover showing HeaderDoc in action.

HeaderDoc tags are placed in comments so they don't affect how your code runs. There are three types of comments that HeaderDoc will recognize:
/**
 This comment can take up multiple lines.
 */

/*! This comment starts on the topmost line.
 * Adding asterisks to the beginning of each line is optional,
 * but you have to be consistent.
 */

/// This is a single-line comment.

I haven't been able to find a good quick reference to the different HeaderDoc tags, so I'll do my best to list the tags I've found here.

 Tag

 Example Usage

 Description

 @@ or \@  Include a single @ in the output.
 \\  Include a single \ in the output.
 @a @a word The next word is in Italic text.
 @abstract  A short overview of what the code does. This will always appear first in the description, and this is the only text that shows up in Xcode's autocomplete pop-up. An @abstract can span multiple lines.
 @attention  Attention text.
 @author  The author. Usually used at the beginning of a file.
 @availability  The version in which this code was first added. Reserved for Apple's own documentation, it doesn't work for you or me.
 @b @b word Synonym for @bold
 @bold @b word The next word is in Bold text
 @brief  A synonym for @abstract, except @brief stops at the first blank line.
 @bug  A brief description of a bug.
 @c @c word Monospaced font, for the next word only
 @class  A short overview of the purpose of the class.
 @code @code
// Print a message
if(true) {
    NSLog(@"Hi");
}@endcode
 Start a block of code. This can be multiple lines, and is printed in a monospaced font. It ends with @endcode
 @const  Synonym for @constant.
 @constant @constant height
The height of the window.		 
 @copyright @copyright Justin Loew The copyright text. Usually used at the beginning of a file.
 @date @date 7/22/2014 The date the file was created. Usually used at the beginning of a file.
 @deprecated  A warning not to use this code because while the code still works, support for it will be ending soon. Reserved for Apple's own documentation, it doesn't work for you or me.
 @description  
 @discussion  A more long-winded description of the code. The discussion starts after this tag, and it can span multiple lines or even paragraphs. It keeps going until it either encounters the next tag or the comment ends. The first chunk of text that doesn't belong to another tag may be used as the discussion by default, if a @discussion is not explicitly written.
 @em @em word Italic text for the next word only. Em is short for emphasis. Synonym for @a
 @endcode @code
// Print a message
if(true) {
    NSLog(@"Hi");
}@endcode		 End the block of code started by @code
 @enum @enum units The unit system to use. 
 @file @file MyFile.m 
 @func @func myFunction A very useful function. Synonym for @function
 @function @function myFunction
An even more useful function.		 A comment about a function. This tag should be the first in the comment.
 @header  This introduces a header file.
 @interface @interface AppDelegate A way for this class to talk back. 
 @invariant  I have no idea what this is.
 @link  I have no idea how to use this. I've never gotten it to work.
 @method  Synonym for @function.
 @namespace  The namespace of the code, for languages that have this feature.
 @note  A short note of something noteworthy about the code or its usage.
 @p  Monospaced font for the next word. Synonym for @c
 @param  Followed by the name of a parameter, then a description of the parameter. Only used when documenting functions. This tag can be used multiple times.
 @post  A postcondition of the function. Only used when documenting functions.
 @pre  A precondition of the function. Only used when documenting functions.
 @property  Just like @var, but for Objective-C properties.
 @protocol  A brief description of an Objective-C protocol.
 @ref  Short for reference. Reserved for Apple's own documentation, it doesn't work for you or me. This is the link at the bottom of the pop-up that opens the documentation to the given method or class.
 @remarks  
 @related  This just names a relevant class or function. Reserved for Apple's own documentation, it doesn't work for you or me.
 @result  Synonym for @return
 @return @return true if the input is even, otherwise false. Describes the value returned by a method or function. 
 @returns  Synonym for @return
 @sa  Synonym for @seealso
 @see  Another bit of code that may be relevant or useful to the reader. Provides further reading on the code at hand.
 @seealso  Similar to @see.
 @since  When the code was first created.
 @struct  Describes a struct, in languages that support structs.
 @throws @throws an_exception An exception that may be thrown, for languages that support this feature. This tag may be used multiple times.
 @todo @todo Get rid of owls. A short note on something that still needs to be done.
 @tparam @tparam height How tall it is. tparam is short for template parameter. Same syntax as @param
 @typedef  Describes what the typedef does and why it exists. For languages that support typedefs.
 @updated @updated 2014-07-22 When the last major change to the code was made.
 @var @var count Used for counting. Synonym for @variable
 @variable @variable varName Description of varName. Describes a variable. Use it to say what the variable represents or holds.
 @version @version 1.0 The version number of the code.
 @warning @warning Code isn't done. A short description of anything one should take heed of.

println("Hi Justin, thank you for writing this tutorial!")
Comments