chapter_3_section_2.html [plain text]
<html>
<head>
<META NAME="Generator" CONTENT="Gutenberg">
<META NAME="GeneratorVersion" CONTENT="v100.1">
<META http-equiv="content-type" CONTENT="text/html;charset=iso-8859-1">
<META NAME = "Copyright" CONTENT="Copyright 2004 Apple Computer, Inc. All Rights Reserved.">
<TITLE>HeaderDoc Unfettered: Introduction to HeaderDoc Comments and Tags</TITLE>
<base target="content">
<LINK REL="stylesheet" TYPE="text/css" HREF="../Resources/CSS/frameset_styles.css">
<style type="text/css"></style>
<script language="JavaScript" src="../Resources/JavaScript/page.js"></script>
</head>
<BODY bgcolor="#ffffff" onload="initialize_page();"><a name="//apple_ref/doc/uid/TP40001215-CH346-DontLinkElementID_872" title="Introduction to HeaderDoc Comments and Tags" turn_anchor="no"></a>
<a name="top"></a>
<!-- start of header -->
<!--#include virtual="/includes/framesetheader" -->
<!-- end of header -->
<!-- start of path -->
<div class="breadcrumb"><a href="http://developer.apple.com/" target="_top">ADC Home</a> > <!--a logicalPath="//apple_ref/doc/uid/TP30000943" -->Reference Library<!--/a--> > <!--a logicalPath="Unknown" -->Technology TBD<!--/a--> > <a logicalPath="//apple_ref/doc/uid/TP40001215-CH345" href="../intro/chapter_1_section_1.html#//apple_ref/doc/uid/TP40001215-CH345">HeaderDoc Unfettered</a> > <a logicalPath="//apple_ref/doc/uid/TP40001215-CH346" href="chapter_3_section_1.html#//apple_ref/doc/uid/TP40001215-CH346">HeaderDoc Tags</a> > </div><br>
<!-- end of path -->
<table width="100%" cellpadding=0 cellspacing=0 border=0 class="mini_nav_text"><tr>
<td align=left scope="row">
<!-- insert Show/Hide frames -->
<script type="text/javascript" language="JavaScript"><!--
if (self != top) {
document.write('<a href="'+self.location+'" target="_top"><img src="../Resources/Images/show_toc_icon.gif" width="15" height="14" border="0" style="margin-bottom: -2px;" alt=""></a> <a href="'+self.location+'" target="_top">Hide TOC</a>');
}
else {
document.write('<a href="../index.html?'+self.location+'" target="_top"><img src="../Resources/Images/show_toc_icon.gif" width="15" height="14" border="0" style="margin-bottom: -2px;" alt=""></a> <a href="../index.html?'+self.location+'" target="_top">Show TOC</a>');
}
<!-- end Show/Hide frames -->
</td><td align=right>
<a href="chapter_3_section_1.html" target="_self">< Previous Page</a><span style="margin-left: 8px"><a href="chapter_3_section_3.html" target="_self">Next Page ></a></span>
</td>
</tr></table>
<hr>
<br><h2>Introduction to HeaderDoc Comments
and Tags</h2>
<p>HeaderDoc comments are of the form:</p>
<table><table cellpadding="8" width="100%" bgcolor="#F1F5F9" style="border: 1px solid #C9D1D7;"><tr><td scope="row"><table bgcolor="#F1F5F9" width="100%" border="0" cellspacing="0" cellpadding="0"><tr><td><pre><code></code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code></code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code>char *FunctionName(int k);</code></pre></td><td><code><pre></pre></code></td></tr></table></td></tr></table></table>
<p>In their simplest form (as above) they differ from standard
C comments only by the addition of the “!” character next to
the opening asterisk.</p>
<p>Historically, HeaderDoc tags also required the addition of
a tag that announces the type of API being commented (“<b>@function</b>”,
below). Beginning in HeaderDoc 8, this tag became optional.</p>
<table><table cellpadding="8" width="100%" bgcolor="#F1F5F9" style="border: 1px solid #C9D1D7;"><tr><td scope="row"><table bgcolor="#F1F5F9" width="100%" border="0" cellspacing="0" cellpadding="0"><tr><td><pre><code></code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code>char *FunctionName(int k);</code></pre></td><td><code><pre></pre></code></td></tr></table></td></tr></table></table>
<p>However, Providing these tags can, in some cases, be used
to cause HeaderDoc to document something in a different way. One
example of this is the use of the <b>@class</b> to modify
the markup of a typedef, as described in <span class="content_text"><a logicalPath="//apple_ref/doc/uid/TP40001215-CH346-CIHDCIGC" href="chapter_3_section_9.html#//apple_ref/doc/uid/TP40001215-CH346-CIHDCIGC">“C Pseudoclass Tags”</a></span>.</p>
<table><table cellpadding="8" width="100%" bgcolor="#F1F5F9" style="border: 1px solid #C9D1D7;"><tr><td scope="row"><table bgcolor="#F1F5F9" width="100%" border="0" cellspacing="0" cellpadding="0"><tr><td><pre><code></code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code>typedef struct foo {...};</code></pre></td><td><code><pre></pre></code></td></tr></table></td></tr></table></table>
<p>You can also 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>
<table><table cellpadding="8" width="100%" bgcolor="#F1F5F9" style="border: 1px solid #C9D1D7;"><tr><td scope="row"><table bgcolor="#F1F5F9" width="100%" border="0" cellspacing="0" cellpadding="0"><tr><td><pre><code></code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code> </code></pre></td><td><code><pre></pre></code></td></tr></table></td></tr></table></table>
<p>Tags are indicated by the “@” character, which must generally
appear as the first non-whitespace character on a line (with a few
notable exceptions). If you need to include an at sign in the output
(to put your email address in a class discussion, for example),
you can do this by prefixing it with a backslash, that is “\@”.</p>
<p>The first tag in a comment announces the API type of the declaration
(function, struct, enum, and so on). This tag is optional. If you
leave it out, HeaderDoc will pick up this information from the declaration
immediately following the comment.</p>
<p>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>
<table><table cellpadding="8" width="100%" bgcolor="#F1F5F9" style="border: 1px solid #C9D1D7;"><tr><td scope="row"><table bgcolor="#F1F5F9" width="100%" border="0" cellspacing="0" cellpadding="0"><tr><td><pre><code></code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code> </code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code> </code></pre></td><td><code><pre></pre></code></td></tr></table></td></tr></table></table>
<p>...and you can use leading asterisks on each line of a multiline
comment:</p>
<table><table cellpadding="8" width="100%" bgcolor="#F1F5F9" style="border: 1px solid #C9D1D7;"><tr><td scope="row"><table bgcolor="#F1F5F9" width="100%" border="0" cellspacing="0" cellpadding="0"><tr><td><pre><code></code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code> </code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code> </code></pre></td><td><code><pre></pre></code></td></tr></table></td></tr></table></table>
<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>
<table><table cellpadding="8" width="100%" bgcolor="#F1F5F9" style="border: 1px solid #C9D1D7;"><tr><td scope="row"><table bgcolor="#F1F5F9" width="100%" border="0" cellspacing="0" cellpadding="0"><tr><td><pre><code></code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code> </code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code> </code></pre></td><td><code><pre></pre></code></td></tr></table></td></tr></table></table>
<p>...will be formatted as two paragraphs in the HTML output: </p>
<br><h3>HMBalloonRect</h3>
<p><tt>OSErr <b>HMBalloonRect</b> (const
HMMessageRecord *inMessage, Rect *outRect);</tt></p>
<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>
<br><br>
<table width="100%" cellpadding=0 cellspacing=0 border=0 class="mini_nav_text"><tr>
<td align=left scope="row">
<!-- insert Show/Hide frames -->
<script type="text/javascript" language="JavaScript"><!--
if (self != top) {
document.write('<a href="'+self.location+'" target="_top"><img src="../Resources/Images/show_toc_icon.gif" width="15" height="14" border="0" style="margin-bottom: -2px;" alt=""></a> <a href="'+self.location+'" target="_top">Hide TOC</a>');
}
else {
document.write('<a href="../index.html?'+self.location+'" target="_top"><img src="../Resources/Images/show_toc_icon.gif" width="15" height="14" border="0" style="margin-bottom: -2px;" alt=""></a> <a href="../index.html?'+self.location+'" target="_top">Show TOC</a>');
}
<!-- end Show/Hide frames -->
</td><td align=right>
<a href="chapter_3_section_1.html" target="_self">< Previous Page</a><span style="margin-left: 8px"><a href="chapter_3_section_3.html" target="_self">Next Page ></a></span>
</td>
</tr></table>
<br><hr><p class="content_text"> <!--#if expr="0=1" -->© 1999, 2004 Apple Computer, Inc. All Rights Reserved. (<!--#endif -->Last updated: 2004-05-27<!--#if expr="0=1" -->)<!--#endif --></p>
<!-- start of footer -->
<!--#include virtual="/includes/framesetfooter" -->
<!-- end of footer -->
</BODY>
</html>