Tools: HeaderDoc User's Guide: Tags for All Headers

## Tags for All Headers

Often, you'll want to add a comment for the header as a whole in addition to comments for individual API elements. For example, if the header declares API for a specific manager (in Mac OS terminology), you may want to provide introductory information about the manager or discuss issues that apply to many of the functions within the manager's API. Likewise, if the header declares a C++ class, you could discuss the class in relation to its superclass or subclasses.

The value you give for the `@header` tag serves as the title for the HTML pages generated by `headerDoc2HTML`. The text you associate with the `@header` tag is used for the introductory page of the HTML website the script produces.

In general, however, you will not specify a filename in the `@header` tag, and will simply let HeaderDoc substitute the filename. Note that you must follow `@header` by a line break; otherwise, the first line of your documentation will be treated as if it were the name of the header.

The tags in the table below (with the exception of `@header`, which must be at the start of a comment block) can be used in any comment for any data type, function, header, or class.

Note: Some tags are marked as inline-compatible. This means that they can be used in the middle of a text container such as `@discussion` or `@abstract`, and that their contents will appear within the existing text flow.

Non–inline-compatible tags terminate the existing text container and create a new one.

Table 2-2 :

Tag | Example | Identifies | Fields
--- | --- | --- | ---
`@abstract` | `@abstract write the track to disk` | A short string that briefly describes a function, data type, and so on. This should not contain multiple lines (because it will look odd in the mini-TOCs). Save the detailed descriptions for the discussion tag. | 1
`@availability` | `@availability 10.3 and later` | A string that describes the availability of a function, class, and so on. | 1
`@copyright` | `@copyright Apple` | Copyright info to be added to each page. This overrides the config file value and may not span multiple lines. | 1
`@deprecated` | `@deprecated in version 10.4` | String telling when the function, data type, etc. was deprecated. | 1
`@discussion` | `@discussion This is what this function does. @some_other_tag` | A block of text that describes a function, class, header, or data type in detail. This may contain multiple paragraphs. `@discussion` may be omitted, as described above. `@discussion` must be present if you have a multiword name for a data type, function, class, or header. An `@discussion` block ends only when another block begins, such as an `@param` tag. | block
`@header` | `@header Repast Manager` | The name under which the API is categorized. Leave the name blank to just use the header filename. The following subtags are available: `@CFBundleIdentifier` STRING: which kernel subcomponent or loadable extension contains this header `@charset` STRING: sets the character encoding for generated HTML files (same as `@encoding`). `@compilerflag` TERM/DEFINITION: compiler flag that should be set. `@encoding` STRING: sets the character encoding for generated HTML files (same as `@charset`). `@flag` TERM/DEFINITION: same as `@compilerflag`. `@ignore` STRING: token to ignore. `@ignorefuncmacro` STRING: function-like macro to ignore. `@preprocinfo` BLOCK: description of behavior when `#define DEBUG` is set, and so on. `@related` TERM/DEFINITION indicates another header that is related to this one. You may use multiple `@related` tags. Explanation of types: STRING: single string, like @abstract TERM/DEFINITION: <name> <description>, like @enum BLOCK: block of text like @discussion | 0/1
`@link` | `@link apple_ref//c/func/function_name link text goes here @/link` or `@link function_name link text goes here @/link` | Allows you to insert a link request for an API ref. If the link target is part of the same `.h` file, you can do this by using only the name of the function or data type. If it is in a separate file (or if there are multiple matches for a given name), you must explicitly specify which API ref to use. Because the `headerDoc2HTML` script does not know the actual target for these links, it inserts comments into the output. You must then run `gatherHeaderDoc` to actually turn those comments into working links. This tag is an inline-compatible tag. | 1
`@meta` | `@meta robots index,nofollow` or `@meta http-equiv=”refresh” content=”0;http://www.apple.com”` | Meta tag info to be added to each page. This can be either in the form `@meta <name> <content>` or `@meta <complete tag contents>`, and may not span multiple lines. | 1
`@namespace` | `@namespace BSD Kernel` | String describing the namespace in which the function, data type, etc. exists. | 1
`@textblock` | `@textblock My text goes here @/textblock` | Treat everything until the trailing `@/textblock` as raw text, preserving initial spaces and line breaks, and converting “<” and “>” to “&lt;” and “&gt;”. Note that this tag does not automatically insert <pre> or <tt>. You may wrap it with whatever formatting you choose. This tag is an inline-compatible tag. | block
`@updated` | `@updated 2003-03-14` | The date at which the header was last updated. | 1
`@version` | `@version 2.3.1` | the version number to which this documentation applies. | 1

Listing 2-3 : Example of `@header` tag

| `
`
    /*!
| `
`
     @header Repast Manager
| `
`
     The Repast Manager provides a functional interface to the repast driver.
| `
`
     Use the functions declared here to generate, distribute, and consume meals.
| `
`
     @copyright Dave's Burger Palace
| `
`
     @updated 2003-03-14
| `
`
     @meta http-equiv=”refresh” content=”0;http://www.apple.com”
| `
`
    */
| `
`

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