<html> <head> <title>HeaderDoc</title> </head> <body bgcolor="white"> <h1>HeaderDoc:<br> API Documentation from Header Files <hr> </h1> <address>Author: Matt Morse (matt@apple.com)</address> <address>Last modified: 07/23/2003</address> <address> </address> <h2>Table of Contents</h2> <ul> <li><a href="#Anchor-Purpose-58644">Purpose</a> <li><a href="#Anchor-Description-39842">Running the Scripts</a> <ul> <li><a href="#runningHeader">Running headerDoc2HTML.pl</a></li> <li><a href="#runningGather">Running gatherHeaderDoc.pl</a></li> <li><a href="#macperl">Running the Scripts using MacPerl</a></li> </ul> <li><a href="#configFile">The Configuration File</a> <li><a href="#Anchor-Tags-40878">HeaderDoc Comments and Tags</a> <li><a href="#Anchor-Tags-49575">Tags for all Headers</a> <li><a href="#Anchor-Tags-35882">Tags by Language Type</a> <ul> <li><a href="CHeaderTags.html">Tags for C headers</a> <li><a href="ObjCTags.html">Tags for Objective-C headers</a> <li><a href="CPPTags.html">Tags for C++ headers</a> </ul> <li><a href="HeaderDocClassHierarchy.html">HeaderDoc's Class Hierarchy</a> <li><a href="ReleaseNotes.html">Release Notes</a> </ul> <h2><a name="Anchor-Purpose-58644"></a>Purpose</h2> <p>HeaderDoc is a system for embedding structured commentary in C and C++ header files and producing rich HTML output from that commentary. HeaderDoc comments are similar in appearance to JavaDoc comments in a Java source file, but there are differences related to handling specifics of C and C++ and to providing a slightly more formal tag set to simplify parsing.</p> <p>A simple HeaderDoc comment for a function might look like this:</p> <pre> /*! @function HMBalloonRect @discussion Use HMBalloonRect to get information about the size of a help balloon before the Help Manager displays it. @param inMessage The help message for the help balloon. @param outRect The coordinates of the rectangle that encloses the help message. The upper-left corner of the rectangle has the coordinates (0,0). */ OSErr HMBalloonRect (const HMMessageRecord *inMessage, Rect *outRect);</pre> <p> When converted to HTML (by <b>headerDoc2HTML</b>, described below), the tagged comment above produces this output:</p> <p><table border="0" cellpadding="0" cellspacing="2" width="92%" bgcolor="#99cccc"> <tr> <td> <h3>HMBalloonRect</h3> <blockquote> <p><tt>OSErr <b>HMBalloonRect</b> (const HMMessageRecord *inMessage, Rect *outRect);</tt><br> </p> </blockquote> <p>Use HMBalloonRect to get information about the size of a help balloon before the Help Manager displays it.</p> <h4>Parameters</h4> <blockquote> <p><table border="1" width="90%"> <tr> <th>Name</th> <th>Description</th> </tr> <tr> <td align="center"><tt>inMessage</tt></td> <td>The help message for the help balloon.</td> </tr> <tr> <td><tt>outRect</tt></td> <td>The coordinates of the rectangle that encloses the help message. The upper-left corner of the rectangle has the coordinates (0,0).</td> </tr> </table></blockquote> </td> </tr> </table></p> <p><font color="black">Also included with the main script (<b>headerDoc2HTML</b>) is <b>gatherHeaderDoc</b>, a utility script that creates a master table of contents for all documentation generated by headerDoc2HTML. Information on running <b>gatherHeaderDoc</b> is provided in the next section.</font></p> <h2><a name="Anchor-Description-39842">Running the Scripts</a></h2> <p><font color="black">HeaderDoc includes two scripts, <b>headerDoc2HTML.pl</b> which generates documentation for each header it encounters, and <b>gatherHeaderDoc.pl</b> which finds these islands of documentation and assembles a master table of contents linking them together.</font></p><br> <h3><a name="runningHeader">Running headerDoc2HTML.pl</a></h3> <p><font color="black">Once you have a header containing HeaderDoc comments, you can run the headerDoc2HTML.pl script to generate HTML output like this:</font></p> <pre> > headerDoc2HTML.pl MyHeader.h</pre> <p> <font color="black">This will process "MyHeader.h" and create an output directory called "MyHeader" in the same directory as the input file. To view the results in your web browser, open the file<b> index.html</b> that you find inside the output directory.</font></p> <p><font color="black">Instead of specifying a single input file (as above), you can specify an input directory, if you wish. HeaderDoc will process every '.h' file in the input directory (and all of its subdirectories), generating an output directory of HTML files for each header that contains HeaderDoc comments.</font></p> <p><font color="black">If you want to specify another directory for the output, use the "-o" switch:</font></p> <pre> > headerDoc2HTML.pl -o /tmp MyHeader.h </pre> <p> <p><font color="black">HeaderDoc normally lists the name of each file it processes to the Terminal. The "-q" switch makes HeaderDoc operate silently:</font></p> <pre> > headerDoc2HTML.pl -q MyHeader.h > headerDoc2HTML.pl -qo /tmp MyHeader.h </pre> <p> <font color="black">The "-H" switch turns on inclusion of the htmlHeader line, as specified in the config file.</font></p> <p> <font color="black">The "-X" switch causes headerdoc to output XML content instead of HTML.</font></p> <p> <font color="black">The "-d" switch turns on extra debugging output.</font></p> <p> <font color="black">The "-h" switch causes HeaderDoc to output an XML file containing metadata about the headerdoc output.</font></p> <p> <font color="black">The "-u" switch disables sorting of functions, data types, and so on.</font></p> <p> <font color="black">You can use the "-v" switch to make HeaderDoc report the versions of all its constituent modules. This can be useful for bug reporting purposes.</font></p> <pre> > headerDoc2HTML.pl -v </pre> <br> <h3><a name="runningGather">Running gatherHeaderDoc.pl</a></h3> <p><font color="black">This script scans an input directory (recursively) for any documentation generated by headerDoc2HTML. It creates a master table of contents (named MasterTOC.html by default--the name can be changed by setting a new name in the configuration file). It also adds a "top" link to all the documentation sets it visits to make it easier to navigate back to the master table of contents. </font></p> <p><font color="black">Here's an example of how to create documentation for a number of headers (the sample ones provided with the scripts) and then generate a master table of contents:</font></p> <pre> > headerDoc2HTML.pl -o OutputDir ExampleHeaders > gatherHeaderDoc.pl OutputDir </pre> <p><font color="black">You can now open the file <tt>OutputDir/MasterTOC.html</tt> in your browser to see the interlinked sets of documentation.</font></p> <br> <h3><a name="macperl">Running the Scripts using MacPerl</a></h3> HeaderDoc runs on Mac OS 9 and earlier assuming MacPerl is installed. (You can get MacPerl from the <a href="http://www.perl.com/CPAN-local/ports/index.html">CPAN ports</a> page.) Here's what you need to do to run HeaderDoc using MacPerl: <ul> <li>Change the line endings in the scripts and modules (*.pm files) from UNIX to Macintosh. Many text editors (BBEdit, for example) let you easily change line ending types.</li> <li>Run MacPerl, open headerDoc2HTML.pl and gatherHeaderDoc.pl and save them as droplets. You might save them with a different names (say, the script names minus the '.pl' extensions) to preserve the original versions.</li> <li>Now, you can drag a header file or folder of header files on each droplet in turn, and the files will be processed in place.</li> </ul> <br> <h2><a name="configFile">The Configuration File</a></h2> <p><font color="black">You can set values for some commonly altered variables. Currently, the configuration file lets you set these things:</font></p> <blockquote> <dl> <dt><b>copyrightOwner</b></dt><dd>The copyright notice that appears at the bottom of the HTML pages. Unless you specify a value, no copyright will appear.</dd> <dt><b>defaultFrameName</b></dt><dd>The name of the file containing the frameset instructions (by default, <tt>index.html</tt>).</dd> <dt><b>compositePageName</b></dt><dd>The name of the file containing the printable HTML page (by default, <tt>CompositePage.html</tt>).</dd> <dt><b>masterTOCName</b></dt><dd>The name of the file containing the master table of contents for a series of headers (by default, <tt>MasterTOC.html</tt>). (This variable is used by the gatherHeaderDoc script.)</dd> <dt><b>apiUIDPrefix</b></dt><dd>The prefix for named anchors in the HTML (by default, <tt>apple_ref</tt>). (In the HTML, HeaderDoc adds a self-describing named anchor near each API declaration -- for example <a name="//apple_ref/c/func/CFArrayAppendValue">. These can be useful for index generation and other purposes. See <a href="APIAnchors.html">Symbol Markers for HTML-based Documentation</a> for more information.)</dd> <dt><b>ignorePrefixes</b></dt><dd>A list of tokens to leave out of the final output if they occur at the start of a line (before any other non-whitespace characters).</dd> <dt><b>htmlHeader</b></dt><dd>A string (generally a server-side include directive) that headerdoc will insert into the top of each right-side and composite HTML page if you specify the -H flag on the command line.</dd> </dl> </blockquote> <p><font color="black">HeaderDoc looks in three places for values for these variables, in this order:</font></p> <ol> <li>In the script itself (see the declaration of the <tt>%config</tt> hash near the top of <tt>headerDoc2HTML</tt>).</li> <li>In the home directory of the user, in <tt>Library/Preferences/com.apple.headerDoc2HTML.config</tt></li> <li>In a file named <tt>headerDoc2HTML.config</tt> in the same folder as the script. </li> </ol> <p><font color="black">A variable can be assigned a value in any of these places, but only the last value read for a given variable will affect the output of a run of the script. If you are happy with the default values for these variables (as described above), you don't need to provide a configuration file. If you want to change just one or more values, provide a configuration file that declares just those values. </font></p> <p><font color="black">The format of the configuration file is this:</font></p> <pre> key1 => value1 key2 => value2 </pre> <p><font color="black">Here is a <a href= "headerDoc2HTML.config.html"> sample configuration file</a>.</font></p><br> <h2> <a name="Anchor-Tags-40878"></a>HeaderDoc Comments and Tags</h2> <p>HeaderDoc comments are of the form:</p> <pre> /*! @function FunctionName This is a comment about FunctionName. */</pre> <p> In their simplest form (as above) they differ from standard C comments in only two ways:</p> <ol> <li>The addition of the "!" character next to the opening asterisk <li>The addition of a tag that announces the type of API being commented ("@function", above). </ol> <p>However, you can use additional JavaDoc-like tags within the HeaderDoc comment to identify specific fields of information. These tags will make the comments more amenable to conversion to HTML. For example, a more complete comment might look like this:</p> <pre> /*! @function HMBalloonRect @abstract Reports size and location of help ballon. @discussion Use HMBalloonRect to get information about the size of a help balloon before the Help Manager displays it. @param inMessage The help message for the help balloon. @param outRect The coordinates of the rectangle that encloses the help message. The upper-left corner of the rectangle has the coordinates (0,0). */</pre> <p> Tags are indicated by the "@" character, which must appear as the first non-whitespace character on a line.</p> <p>The first tag in a comment announces the API type of the declaration (function, struct, enum, and so on). The next two lines (tagged @abstract and @discussion) provide documentation about the API element as a whole. The abstract can be used in summary lists, and the discussion can be used in the detailed documentation about the API element.</p> <p>The abstract and discussion tags are optional, but encouraged. Their use enables various improvements in the HTML output, such as summary pages. However, if there is untagged text following the API type tag and name (@function HMBalloonRect, above) it is assumed to be a discussion. With such untagged text, HeaderDoc assumes the discussion extends from the end of the API-type comment to the next HeaderDoc tag or to the end of the HeaderDoc comment, whichever occurs first.</p> <p>HeaderDoc understands some variants in commenting style. In particular, you can have a one-line comment like this:</p> <pre> /*! @var settle_time Latency before next read. */ </pre> <p> ...and you can use leading asterisks on each line of a multiline comment:</p> <pre> /*! * @function HMBalloonRect * @abstract Reports size and location of help ballon. * @discussion Use HMBalloonRect to get information about the size of a help balloon * before the Help Manager displays it. * @param inMessage The help message for the help balloon. * @param outRect The coordinates of the rectangle that encloses the help message. * The upper-left corner of the rectangle has the coordinates (0,0). */ </pre> <p> If you want to specify a line break in the HTML version of a comment, use two carriage returns between lines rather than one. For example, the text of the discussion in this comment:</p> <pre> /*! * @function HMBalloonRect * @discussion Use HMBalloonRect to get information about the size of a help balloon * before the Help Manager displays it. * * By checking the help balloon size before display, you can guard against... */ </pre> <p> ...will be formatted as two paragraphs in the HTML output: </p> <p><table border="0" cellpadding="0" cellspacing="2" width="92%" bgcolor="#99cccc"> <tr> <td> <h3>HMBalloonRect</h3> <blockquote> <p><tt>OSErr <b>HMBalloonRect</b> (const HMMessageRecord *inMessage, Rect *outRect);</tt><br> </p> </blockquote> <p>Use HMBalloonRect to get information about the size of a help balloon before the Help Manager displays it.</p> <p>By checking the help balloon size before display, you can guard against...</p> <p> </td> </tr> </table></p> <p> </p> <h2><a name="Anchor-Tags-49575"></a>Tags for All Headers</h2> <p>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.</p> <p>The value you give for the @header tag serves as the title for the HTML pages generated by <b>headerDoc2HTML</b>. The text you associate with the @header tag is used for the introductory page of the HTML website the script produces.</p> <p><table border="1" cellpadding="0" cellspacing="2" width="92%"> <tr> <td> <center> <b>Tag</b></center> </td> <td width="200"> <center> <b>Example</b></center> </td> <td> <center> <b>Identifies</b></center> </td> <td> <center> <b>Fields </b></center> </td> </tr> <tr> <td><b>@header</b></td> <td width="200"><tt>@header Repast Manager</tt></td> <td>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)</td> <td> <center> 1</center> </td> </tr> <tr> <td><b>@copyright</b></td> <td width="200"><tt>@copyright Apple</tt></td> <td>Copyright info to be added to each page. This overrides the config file value and may not span multiple lines.</td> <td> <center> 1</center> </td> </tr> <tr> <td><b>@meta</b></td> <td width="200"><tt>@meta robots index,nofollow</tt><br><tt>@meta http-equiv="refresh" content="0;http://www.apple.com"</tt></td> <td>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.</td> <td> <center> 1</center> </td> </tr> <tr> <td><b>@availability</b></td> <td width="200"><tt>@availability 10.3 and later</tt></td> <td>A string that describes the availability of a function, class, and so on.</td> <td> <center> 1</center> </td> </tr> <tr> <td><b>@updated</b></td> <td width="200"><tt>@updated 2003-03-14</tt></td> <td>The date at which the header was last updated.</td> <td> <center> 1</center> </td> </tr> </table></p> <p><b>Example: </b></p> <pre> /*! @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" */</pre> <h2> <a name="Anchor-Tags-35882"></a>Tags By Language Type</h2> <p>Tags are largely specific to a particular programming language—the @method tag has no place in a C header, for example. Refer to the following sections for information about which tags are available for a particular language context.</p> <ul> <li><a href="CHeaderTags.html">Tags for C headers</a> <li><a href="ObjCTags.html">Tags for Objective-C headers</a> <li><a href="CPPTags.html">Tags for C++ headers</a> </ul> <p> </p> <p> </p> <p> </body> </html>