Tools: HeaderDoc Unfettered: 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

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.

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.

Tag | Identifies | Fields
--- | --- | ---
`@method` | The method name followed by the description. | 2
`@param` | The parameter name followed by the description. | 2
`@result` | The return value of the method. | 1

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)