Tags for Objective-C Headers

• Introduction
• Conventions Used in this Documentation
• Additional Tags for Objective-C Declarations
  • The @class and @protocol Tags
  • The @method Tag

Introduction

HeaderDoc processes a Objective-C header in much the same way that it does a C header. In fact, until HeaderDoc encounters a class declaration in an Objective-C header, the processing is identical. This means you can use any of the tags defined for C headers within an Objective-C header. See Tags for C Headers.

For example, in a header that declares two classes, you may want to use the @header tag to provide a discussion explaining why these classes are grouped, and use the @class tags to provide discussions for each of the classes. Within the class declarations, you can use the @method tag to document each method. Since Objective-C is a superset of C, the header might also declare types, functions, or other API outside of any class declaration. You would use @typedef, @function, and other C tags to document these declarations.

Processing Objective-C Classes

Once HeaderDoc encounters an @class tag (with accompanying declaration) in an Objective-C header, it treats all comments and declarations that follow—until the end of the class declaration—as belonging to that class, rather than to the header as a whole. When HeaderDoc generates the HTML documentation for an Objective-C header, it creates one frameset for the header as a whole, and separate framesets for each class declared within the header.

Processing Objective-C Protocols

HeaderDoc processes Objective-C protocol declarations similarly to class declarations. The documentation for the protocol and the methods it declares are grouped in their own frameset, which is accessed from the documentation for the header that contains the protocol.

Processing Objective-C Categories

An Objective-C category lets you add methods to an existing class. When HeaderDoc processes a batch of headers and finds comments for methods declared in a category, it searches for the associated class documentation and adds those methods and their documentation to the class documentation. If the class is not present in the current batch, HeaderDoc will create a separate frameset of documentation for the category.

Within a Objective-C class, protocol, or category declaration, HeaderDoc allows the @method tag, as describe below.

Conventions Used in this Documentation

Depending on their type, tags can introduce either one or two fields of information:

@method [MethodName]
@param [parameterName] [Some descriptive text...]

In the tables below, the "Fields" column indicates the number of textual fields each type of tag takes.

The tags highlighted in RED below are required.

The @class, @protocol, and @category Tags

In Objective-C, class and protocol declarations are quite similar, and consequently HeaderDoc's @class and @protocol tags are parallel in their usage.

Class and Protocol Tags

Tag	Identifies	Fields
@class	The name of the class.	1
@category	The full name of the category, as declared in the header. For example, "MyClass(MyCategory)". HeaderDoc uses the "MyClass" portion of the name to identify the associated class.	1
@protocol	The name of the protocol.	1

Following these tags, you typically provide introductory information about the purpose of the class, protocol, or category. You can divide this material into a summary sentence and in-depth discussion (using the @abstract and @discussion tags), or you can provided the material as an untagged block of text, as the examples below illustrate.

Example 1 - Documentation tagged as abstract and discussion:

/*!
   @class NSPrinter
   @abstract An NSPrinter object describes a printer's capabilities.
   @discussion An NSPrinter object describes a printer's capabilities, such as whether the printer can print in color and whether it provides a particular font. An NSPrinter object represents...  
*/
@interface NSPrinter: NSObject 
...
@end

Example 2 - Documentation as single block of text:

/*!
   @class NSPrinter
   An NSPrinter object describes a printer's capabilities, such as whether the printer can print in color and whether it provides a particular font. An NSPrinter object represents...  
*/
@interface NSPrinter: NSObject 
...
@end

The @method Tag

For methods declared in an Objective-C class, protocol, or category, use the @method tag:

Tag	Identifies	Fields
@method	The method name followed by the discription.	2
@param	The parameter name followed by the discription.	2
@result	The return value of the method.	1

Example

/*! 
   @method dateWithString:calendarFormat:   
   @abstract Creates and returns a calendar date initialized with the date 
             specified in the string description. 
   @discussion [An extended description of the method...]
   @param description  A string specifying the date.
   @param format  Conversion specifiers similar to those used in strftime().
   @result  Returns the newly initialized date object or nil on error.
*/
+ (id)dateWithString:(NSString *)description calendarFormat:(NSString *)format;