Languages Supported

HeaderDoc 8 supports many more languages than HeaderDoc 7. This table shows the various languages and the level of support.

Major Features

HeaderDoc 8 has a number of new features.

• Function/data type groupings

• Declaration syntax coloring

• New tagless syntax

  /*! This is a comment about what comes next */

• Support for HeaderDoc tags embedded in declarations

• Support for //! markup style for embedded HeaderDoc declarations

• Automatic linking of data types in declarations

• Improved C++ support (namespace/template/access)

• The gatherheaderdoc tool is now template based

• PHP support (and a bunch of other languages) now included without patching

• Support for linking to other methods and data types within the same file

• Comment stripper

• Support for exceptions

• Now warns if tagged parameters don’t match declaration

• Optional warning if parameters are not tagged

• Improved warnings for other invalid content

• Man page output path (via XML)

• DTD for output validation

• Translation of HTML to XHTML using xmllint when using XML output

• Nested class handling

• Customizable date format

• C pseudoclass support (typedef struct)

• Better nested class support

• C++ constructors/destructors now sorted first in the list of class methods.

• The @ignore tag—allows you to remove matching tokens from declarations

• “Unsorted” flag

• Summary function and method lists (a mini-TOC)

• Automated detection of numbered lists

• Automatic handling of availability macros

• Improved overall appearance

• Includes a regression test suite

New Tags

This section attempts to list all of the new tags added in HeaderDoc 8 (some of which were actually available, but undocumented, in HeaderDoc 7).

@classdesign

Text block describing the overall design of a class

@coclass

String describing a class that this class was designed to work with

@dependency

String describing a class upon which this class depends heavily

@exception

String describing an exception thrown by a function/method/class

@functiongroup

Tag for grouping functions and methods; this takes priority over the @group tag with respect to functions and methods.

@group

Tag for grouping data, functions, and so on, thus changing the order in which they appear in the table of contents.

(Note: the @functiongroup tag takes priority over the @group tag for functions.)

@helper

String telling what helper classes this class uses

@helps

For helper classes, string telling what sort of classes this class was designed to help

@instancesize

Text block containing the size of an instance of this class

@methodgroup

See @functiongroup.

@ownership

String describing what class instantiates the current class (for example, I/O Kit nubs)

@performance

Text block to describe performance characteristics of a class (for example, “This class is not appropriate for use in high-performance environments”)

@security

Text block to describe security considerations when using this class

@superclass

Adds superclass info to a C pseudoclass; also can be used to cause members of the superclass to be merged into the subclass

@throws

See @exception.

Additional Notes

This section lists known issues in HeaderDoc 8. We hope to improve in these areas in future versions. If you find issues not listed here, please file bugs.

• HeaderDoc 8 is somewhat slower than previous versions. This is because the entire parser has been rewritten from the ground up and now does a token-based parse of the input file.

  While this approach should significantly improve the correctness of output (colorizer bugs notwithstanding), it is doing a lot more work than before, and thus takes longer.

• The default color scheme generated by HeaderDoc matches Xcode coloring. There are a number of files supplied as alternative color schemes, ranging from pleasant to utterly hideous and blinking (used mainly for testing). Swap out your headerDoc2HTML.config file as desired.

• Although a minimal gatherheaderdoc template is built into the tool itself, the default template used by gatherheaderdoc is an actual file that comes preinstalled as Xcode.app/Contents/Developer/usr/share/headerdoc/conf/com.apple.headerdoc.exampletocteplate.html inside the Xcode app bundle (or /usr/share/headerdoc/conf/com.apple.headerdoc.exampletocteplate.html if you built HeaderDoc yourself). The format for this template is described in Advanced HeaderDoc Configuration and Features. Also see Example gatherheaderdoc Template for an example of the template format.

Late-Breaking Bugs

This section describes late-breaking bugs in HeaderDoc 8.9.

There are no known errata yet for HeaderDoc 8.9.

To keep up to date with the latest errata and bug fixes, join the headerdoc-dev mailing list.