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.
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.
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.
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.
Depending on their type, tags can introduce either one or two fields of information:
@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.
In Objective-C, class and protocol declarations are quite similar, and consequently HeaderDoc's @class and @protocol tags are parallel in their usage.
|@class||The name of the class.||
|@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.||
|@protocol||The name of the protocol.||
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
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
For methods declared in an Objective-C class, protocol, or category, use the @method tag:
|@method||The method name followed by the discription.||
|@param||The parameter name followed by the discription.||
|@result||The return value of the method.||
/*! @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;