chapter_3_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>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_880" 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="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_9.html" target="_self">< Previous Page</a><span style="margin-left: 8px"><a href="chapter_3_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_3_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 <b>@header</b> tag to provide a discussion
explaining why these classes are grouped, and use the <b>@class</b> tags to
provide discussions for each of the classes.</p>
<p>Once HeaderDoc encounters an <b>@class</b> 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_3_section_10.html#//apple_ref/doc/uid/TP40001215-CH346-CIHCGEIE">Conventions</a>
<br>
<a logicalPath="//apple_ref/doc/uid/TP40001215-CH346-CIHJFJHD" href="chapter_3_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"><b>@function</b> [FunctionName]</li><br>
<li class="content_text"> <b>@param</b> [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>
<td class="content_text" scope="row"><p> <b>Tag</b> </p></td>
<td class="content_text"><p> <b>Identifies</b> </p></td>
<td class="content_text"><p><b>Fields</b></p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><b>@class</b> </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 <b>@class</b> 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 <b>@abstract</b> and <b>@discussion</b> tags),
or you can provided the material as an untagged block of text, as
the examples below illustrate. You can also add <b>@throws</b> tags
to indicate that the class throws exceptions or add an <b>@namespace</b> tag
to indicate the namespace in which the class resides.</p>
<p><b>Example 1 - Documentation tagged as abstract and
discussion:</b></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>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><b>Example 2 - Documentation as single block of text:</b></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>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><b>@classdesign</b></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><b>@coclass</b></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><b>@dependency</b></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><b>@helper</b> or <b>@helperclass</b></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><b>@helps</b></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><b>@instancesize</b></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><b>@ownership</b></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><b>@performance</b></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><b>@security</b></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><b>@superclass</b></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 <b>@superclass</b> tag
is not generally required for superclass information to be included.
The <b>@superclass</b> 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 <b>@function</b> tag
(described in <span class="content_text"><a logicalPath="//apple_ref/doc/uid/TP40001215-CH346-CIHHJCBD" href="chapter_3_section_8.html#//apple_ref/doc/uid/TP40001215-CH346-CIHHJCBD">“Function Tags”</a></span>)
or the <b>@method</b> 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 <b>@templatefield</b> tag.
You should also be sure to define the class using <b>@template</b> instead
of <b>@class</b>.</p>
<p>The <b>@templatefield</b> 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><b>@templatefield</b> </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>
<p><b>Example</b></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>/*! @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 <b>ExampleHeaders</b> 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_3_section_9.html" target="_self">< Previous Page</a><span style="margin-left: 8px"><a href="chapter_3_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>