HeaderDoc Release Notes

HeaderDoc 8 is the latest incarnation of the HeaderDoc tool. HeaderDoc 8.5 is an enhanced version of HeaderDoc 8.

The HeaderDoc Tools Suite consists of a series of Perl scripts and several small C helper applications that allows conversion of documentation embedded in header files in many languages into HTML and other output formats.

HeaderDoc 8 is nearly a rewrite of HeaderDoc from the ground up. It incorporates the functionality of previous versions but also provides a number of new features, such as declaration syntax coloring/highlighting and an easier-to-use comment syntax. These features are described in “Major Features.”

HeaderDoc 8 adds a number of additional languages with various levels of support. These are described in “Languages Supported.”

HeaderDoc 8 also adds a number of new (optional) tags for convenience. These are described in “New Tags.”

Finally, HeaderDoc 8.5 adds a C preprocessor for more advanced header parsing. This is described in “Using the C Preprocessor.”

For additional information, see the documentation that is packaged with HeaderDoc.

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)

• GatherHeaderdoc 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

• Beginnings of 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.

• The GatherHeaderDoc default template is built-in. 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.7.

• C structs with bit fields are parsed incorrectly, leading to warnings that incorrectly claim that parameters do not exist in the declaration.

  For the most part, this bug is cosmetic and can be ignored. It does, however, affect the list of parsed parameters in XML output mode.

  See http://www.darwin-development.org/headerdoc_patches/Snow_Leopard/struct_bitfield_fix.patch for a patch that fixes this bug.

• In some scripting languages, function parameters may be incorrectly colored as types or function names instead of parameters. This bug is strictly cosmetic.

• In iframe output mode, HeaderDoc incorrectly generates links with target="doc" instead of target="_top". As a result, clicking links in the table of contents results in a new window every time.

  You can avoid this problem by using frameset output mode. To enable frameset mode, pass the -F flag to headerdoc2html.

  See http://www.darwin-development.org/headerdoc_patches/Snow_Leopard/iframe_fix.patch for a patch that fixes this bug.

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

---