Tags for Objective-C Headers

Tags for Objective-C Headers

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 Common to All API Types”.

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.

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

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.

Listing 2-22 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 <NSCopying, NSCoding>

...

@end

Listing 2-23 Documentation included 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 <NSCopying, NSCoding$gt;

...

@end

The @method Tag

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

Listing 2-24 Example of @method tag

/*! 

 @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;

For more usage examples, see the ExampleHeaders folder that accompanies the HeaderDoc distribution.

© 1999, 2004 Apple Computer, Inc. All Rights Reserved. (Last updated: 2004-05-27)