< Previous PageNext Page >


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.

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 multi-word 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. Typically used to declare the Manager name (for classic Mac APIs) or class name (for object-oriented APIs)

The following subtags are available:


@CFBundleIdentifier
STRING which kernel subcomponent or loadable extension contains this header

@compilerflag
TERM/DEFINITION compiler flag that should be set.

@flag
TERM/DEFINITION same as @compilerflag.

@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 3-1 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”
*/


< Previous PageNext Page >


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