chapter_2_section_10.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>Tools: HeaderDoc Unfettered: Tags for C++ Headers</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_1056" title="Tags for C++ Headers" 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="//apple_ref/doc/uid/TP30000440" -->Documentation<!--/a--> > <!--a logicalPath="//apple_ref/doc/uid/TP30000436" -->Tools<!--/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_2_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_2_section_9.html" target="_self">< Previous Page</a><span style="margin-left: 8px"><a href="chapter_2_section_11.html" target="_self">Next Page ></a></span>
</td>
</tr></table>
<hr>
<br><h2>Tags for C++ Headers</h2>
<p>HeaderDoc processes a C++ header in much the same way that
it does a C header. In fact, until HeaderDoc encounters a class
declaration in a C++ header, the processing is identical. This means
you can use any of the tags defined for C headers within a C++ header.
See <span class="content_text"><a logicalPath="//apple_ref/doc/uid/TP40001215-CH346-CIHCEBGD" href="chapter_2_section_8.html#//apple_ref/doc/uid/TP40001215-CH346-CIHCEBGD">“Tags for All Languages”</a></span>.</p>
<p>For example, in a header that declares two classes, you may
want to use the <tt>@header</tt> tag
to provide a discussion explaining why these classes are grouped,
and use the <tt>@class</tt> tags
to provide discussions for each of the classes.</p>
<p>Once HeaderDoc encounters an <tt>@class</tt> tag
(with accompanying class declaration) in a C++ header, it treats
all comments and declarations that follow (until the end of the
class declaration) as belonging to that class, rather than to the
header as a whole. When HeaderDoc generates the HTML documentation
for a C++ header, it creates one frameset for the header as a whole,
and separate framesets for each class declared within the header.</p>
<p>HeaderDoc records the access control level (public, protected,
or private) of API elements declared within a C++ class. This information
is used to group the API elements in the resulting documentation.</p>
<p>Within a C++ class declaration, HeaderDoc allows some additional
tags, as describe below.</p>
<h4>In this section:</h4>
<blockquote class="content_text">
<a logicalPath="//apple_ref/doc/uid/TP40001215-CH346-CIHCGEIE" href="chapter_2_section_10.html#//apple_ref/doc/uid/TP40001215-CH346-CIHCGEIE">Conventions</a>
<br>
<a logicalPath="//apple_ref/doc/uid/TP40001215-CH346-CIHJFJHD" href="chapter_2_section_10.html#//apple_ref/doc/uid/TP40001215-CH346-CIHJFJHD">Additional Tags for C++ Class Declarations</a>
<br>
</blockquote>
<a name="//apple_ref/doc/uid/TP40001215-CH346-CIHCGEIE" title="Conventions" turn_anchor="no"></a><a name="CIHCGEIE" title="Conventions" turn_anchor="no"></a><br><h3>Conventions</h3>
<p>Tags, depending on type, can introduce either one or two fields
of information:</p>
<ul class="content_text"><li class="content_text"><tt>@function</tt> [FunctionName]</li><br>
<li class="content_text"> <tt>@param</tt> [parameterName]
[Some descriptive text...]</li><br></ul>
<p>In the tables below, the “Fields” column indicates the
number of textual fields each type of tag takes.</p>
<p> </p>
<a name="//apple_ref/doc/uid/TP40001215-CH346-CIHJFJHD" title="Additional Tags for C++ Class
Declarations" turn_anchor="no"></a><a name="CIHJFJHD" title="Additional Tags for C++ Class
Declarations" turn_anchor="no"></a><br><h3>Additional Tags for C++ Class
Declarations</h3>
<p>Within a C++ class declaration, HeaderDoc understands all
the tags for C headers, along with some new ones which are listed
in the following sections.</p>
<p> </p>
<a name="//apple_ref/doc/uid/TP40001215-CH346-CIHFJJEB" title="Class Tags" turn_anchor="no"></a><a name="CIHFJJEB" title="Class Tags" turn_anchor="no"></a><br><h4>Class Tags</h4>
<p></p><br><table border = "1" cellpadding = "3">
<tr>
<th scope="col"><div align="left"><b><p> Tag </p></b></div></th>
<th scope="col"><div align="left"><b><p> Identifies </p></b></div></th>
<th scope="col"><div align="left"><b><p>Fields</p></b></div></th>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@class</tt> </p></td>
<td class="content_text"><p>The name of the class.</p></td>
<td class="content_text"><p> 1 </p></td>
</tr>
</table><br>
<p>Following the <tt>@class</tt> tag,
you typically provide introductory information about the purpose
of the class. You can divide this material into a summary sentence
and in-depth discussion (using the <tt>@abstract</tt> and <tt>@discussion</tt> tags),
or you can provided the material as an untagged block of text, as
the examples below illustrate. You can also add <tt>@throws</tt> tags to
indicate that the class throws exceptions or add an <tt>@namespace</tt> tag
to indicate the namespace in which the class resides.</p>
<table><p><b><font face="lucida grande, geneva, helvetica, arial, sans-serif" size="2">Listing 2-19 Example
of documentation with @abstract and @discussion tags</font></b></p>
<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>class IOCommandGate: public IOEventSource</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><tr><td scope="row"><pre><code>}</code></pre></td><td><code><pre></pre></code></td></tr></table></td></tr></table></table>
<table><p><b><font face="lucida grande, geneva, helvetica, arial, sans-serif" size="2">Listing 2-20 Example
of documentation as a single block of text</font></b></p>
<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>class IOCommandGate: public IOEventSource</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><tr><td scope="row"><pre><code>}</code></pre></td><td><code><pre></pre></code></td></tr></table></td></tr></table></table>
<p>Classes have many special tags associated with them for convenience.
These include:</p><br><table border = "1" cellpadding = "3">
<tr>
<th scope="col"><div align="left"><b><p>Tag</p></b></div></th>
<th scope="col"><div align="left"><b><p>Disposition</p></b></div></th>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@classdesign</tt></p></td>
<td class="content_text"><p>BLOCK: description of any common design considerations
that apply to this class, such as consistent ways of handling locking
or threading</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@coclass</tt></p></td>
<td class="content_text"><p>TERM/DEFINITION: class with which this class was designed
to work</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@dependency</tt></p></td>
<td class="content_text"><p>STRING: external resource that this class depends on
(such as a class or file)</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@helper</tt> or <tt>@helperclass</tt></p></td>
<td class="content_text"><p>TERM/DEFINITION: helper classes used by this class</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@helps</tt></p></td>
<td class="content_text"><p>STRING: if this is a helper class, short description
of classes that this class was designed to help</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@instancesize</tt></p></td>
<td class="content_text"><p>STRING: the size of each instance of the class</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@ownership</tt></p></td>
<td class="content_text"><p>BLOCK: description of ownership model to which this class
conforms, e.g. MyClass objects are owned by the MyCreatorClass object
that created them</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@performance</tt></p></td>
<td class="content_text"><p>BLOCK: description of this class's special performance
characteristics, e.g. this class is optimized for the Velocity Engine,
or this class is strongly discouraged in high-performance contexts</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@security</tt></p></td>
<td class="content_text"><p>BLOCK: security considerations associated with the use
of this class</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@superclass</tt></p></td>
<td class="content_text"><p>STRING: override superclass name---see note below.</p></td>
</tr>
</table><br>
<p><i>Explanation of types:</i></p>
<ul class="content_text"><li class="content_text"><i>STRING:
single string, like @abstract</i></li><br>
<li class="content_text"><i>TERM/DEFINITION: <name> <description>,
like @enum</i></li><br>
<li class="content_text"><i>BLOCK: block of text like @discussion</i></li><br></ul>
<div class="notebox"><span class="content_text"><b>Note: </b>The <tt>@superclass</tt> tag
is not generally required for superclass information to be included.
The <tt>@superclass</tt> tag has
two purposes:<ul class="content_text">
<li class="content_text">To add "superclass" info to a C pseudo-classes such
as a COM interface (a <tt>typedef struct</tt> containing
function pointers).</li><br>
<li class="content_text">To enable inclusion of superclass functions, types, etc. in
the subclass docs. The superclass <i>MUST</i> be processed
before the subclass (earlier on the command line or higher up in
the same file), or this may not work correctly.</li><br></ul></span></div>
<br><h4>Function
Tags</h4>
<p>For member functions, use the <tt>@function</tt> tag
(described in <span class="content_text"><a logicalPath="//apple_ref/doc/uid/TP40001215-CH346-CIHHJCBD" href="chapter_2_section_8.html#//apple_ref/doc/uid/TP40001215-CH346-CIHHJCBD">“Function Tags”</a></span>) or the <tt>@method</tt> tag
(which behaves identically for C++ methods). </p>
<a name="//apple_ref/doc/uid/TP40001215-CH346-CIHFFJID" title="Template Tags" turn_anchor="no"></a><a name="CIHFFJID" title="Template Tags" turn_anchor="no"></a><br><h4>Template Tags</h4>
<p>For C++ template classes, if you want to document the template
type parameters, you should use the <tt>@templatefield</tt> tag.
You should also be sure to define the class using <tt>@template</tt> instead
of <tt>@class</tt>.</p>
<p>The <tt>@templatefield</tt> tag
can also be used to document template parameters for C++ template
functions.</p><br><table border = "1" cellpadding = "3">
<tr>
<th scope="col"><div align="left"><b><p>Tag</p></b></div></th>
<th scope="col"><div align="left"><b><p>Identifies</p></b></div></th>
<th scope="col"><div align="left"><b><p>Fields</p></b></div></th>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@templatefield</tt> </p></td>
<td class="content_text"><p>The name of the parameter followed by the description.</p></td>
<td class="content_text"><p> 2 </p></td>
</tr>
</table><br>
<table><p><b><font face="lucida grande, geneva, helvetica, arial, sans-serif" size="2">Listing 2-21 Example
of @templatefield tag</font></b></p>
<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>/*! @templatemystackclass</code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code> @templatefieldTthe data type stored in this stack */</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> template <T> class mystackclass</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>For more usage examples, see the <code>ExampleHeaders</code> folder
that accompanies the HeaderDoc distribution. </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) {
// loaded in frames
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 {
// not loaded frames
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>');
}
//--></script>
<!-- end Show/Hide frames -->
</td><td align=right>
<a href="chapter_2_section_9.html" target="_self">< Previous Page</a><span style="margin-left: 8px"><a href="chapter_2_section_11.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>