chapter_2_section_6.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 All 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_1052" title="Tags for All 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_5.html" target="_self">< Previous Page</a><span style="margin-left: 8px"><a href="chapter_2_section_7.html" target="_self">Next Page ></a></span>
</td>
</tr></table>
<hr>
<br><h2>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 <tt>@header</tt> tag
serves as the title for the HTML pages generated by <tt>headerDoc2HTML</tt>.
The text you associate with the <tt>@header</tt> tag
is used for the introductory page of the HTML website the script
produces.</p>
<p>In general, however, you will not specify a filename in the <tt>@header</tt> tag,
and will simply let HeaderDoc substitute the filename. Note that
you must follow <tt>@header</tt> by
a line break; otherwise, the first line of your documentation will
be treated as if it were the name of the header.</p>
<p>The tags in the table below (with the exception of <tt>@header</tt>,
which must be at the start of a comment block) can be used in any
comment for any data type, function, header, or class.</p><div class="notebox"><span class="content_text"><b>Note: </b>Some
tags are marked as inline-compatible. This means that they can be
used in the middle of a text container such as <tt>@discussion</tt> or <tt>@abstract</tt>,
and that their contents will appear within the existing text flow.Non–inline-compatible
tags terminate the existing text container and create a new one.</span></div><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>Example</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>@abstract</tt> </p></td>
<td class="content_text"><p><tt>@abstract write the track to disk</tt></p></td>
<td class="content_text"><p>A short string that briefly describes a function, data
type, and so on. This should not contain multiple lines (because
it will look odd in the mini-TOCs). Save the detailed descriptions
for the discussion tag.</p></td>
<td class="content_text"><p> 1 </p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@availability</tt> </p></td>
<td class="content_text"><p><tt>@availability 10.3 and later</tt></p></td>
<td class="content_text"><p>A string that describes the availability of a function,
class, and so on.</p></td>
<td class="content_text"><p> 1 </p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@copyright</tt> </p></td>
<td class="content_text"><p><tt>@copyright Apple</tt></p></td>
<td class="content_text"><p>Copyright info to be added to each page. This overrides
the config file value and may not span multiple lines.</p></td>
<td class="content_text"><p> 1 </p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@deprecated</tt> </p></td>
<td class="content_text"><p><tt>@deprecated in version 10.4</tt></p></td>
<td class="content_text"><p>String telling when the function, data type, etc. was
deprecated.</p></td>
<td class="content_text"><p> 1 </p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@discussion</tt> </p></td>
<td class="content_text"><p><tt>@discussion This is what this function does.
@some_other_tag</tt></p></td>
<td class="content_text"><p>A block of text that describes a function, class, header,
or data type in detail. This may contain multiple paragraphs. <tt>@discussion</tt> may
be omitted, as described above.</p><p><tt>@discussion</tt> must
be present if you have a multiword name for a data type, function,
class, or header.</p><p>An <tt>@discussion</tt> block
ends only when another block begins, such as an <tt>@param</tt> tag.</p></td>
<td class="content_text"><p> block </p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@header</tt> </p></td>
<td class="content_text"><p><tt>@header Repast Manager</tt></p></td>
<td class="content_text"><p>The name under which the API is categorized. Leave the
name blank to just use the header filename.</p><p>The following subtags
are available:</p><p><dl class="content_text">
<br><dt class="content_text"><tt>@CFBundleIdentifier</tt></dt>
<dd class="content_text">STRING which kernel subcomponent or loadable extension
contains this header</dd>
<br><dt class="content_text"><tt>@compilerflag</tt></dt>
<dd class="content_text">TERM/DEFINITION compiler flag that should be set.</dd>
<br><dt class="content_text"><tt>@flag</tt></dt>
<dd class="content_text">TERM/DEFINITION same as <tt>@compilerflag</tt>.</dd>
<br><dt class="content_text"><tt>@ignore</tt></dt>
<dd class="content_text">token to ignore.</dd>
<br><dt class="content_text"><tt>@preprocinfo</tt></dt>
<dd class="content_text">BLOCK: description of behavior when <tt>#define
DEBUG</tt> is set, and so on.</dd>
<br><dt class="content_text"><tt>@related</tt></dt>
<dd class="content_text">TERM/DEFINITION indicates another header that is related
to this one. You may use multiple <tt>@related</tt> tags.</dd></dl></p><p><i>Explanation
of types:</i></p><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></p></td>
<td class="content_text"><p> 0/1 </p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@link</tt> </p></td>
<td class="content_text"><p><tt>@link apple_reflink text goes here @/link</tt></p><p><i>or</i></p><p><tt>@link
function_name link text goes here @/link</tt></p></td>
<td class="content_text"><p>Allows you to insert a link request for an API ref. If
the link target is part of the same <code>.h</code> file,
you can do this by using only the name of the function or data type.
If it is in a separate file (or if there are multiple matches for
a given name), you must explicitly specify which API ref to use.</p><p>Because
the <code>headerDoc2HTML</code> script does not know the
actual target for these links, it inserts comments into the output.
You must then run <code>gatherHeaderDoc</code> to actually
turn those comments into working links.</p><p><b>This
tag is an inline-compatible tag.</b></p></td>
<td class="content_text"><p> 1 </p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@meta</tt> </p></td>
<td class="content_text"><p><tt>@meta robots index,nofollow</tt></p><p><i>or</i></p><p><tt>@meta
http-equiv=”refresh” content=”0;http://www.apple.com”</tt></p></td>
<td class="content_text"><p>Meta tag info to be added to each page. This can be either
in the form <tt>@meta <name> <content></tt> or <tt>@meta
<complete tag contents></tt>, and may not
span multiple lines.</p></td>
<td class="content_text"><p> 1 </p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@namespace</tt> </p></td>
<td class="content_text"><p><tt>@namespace BSD Kernel</tt></p></td>
<td class="content_text"><p>String describing the namespace in which the function,
data type, etc. exists.</p></td>
<td class="content_text"><p> 1 </p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@textblock</tt> </p></td>
<td class="content_text"><p><tt>@textblock My text goes here @/textblock</tt></p></td>
<td class="content_text"><p>Treat everything until the trailing <tt>@/textblock</tt> as
raw text, preserving initial spaces and line breaks, and converting
“<” and “>” to “&lt;” and “&gt;”.</p><p><i>Note
that this tag does not automatically insert <pre> or <tt>.
You may wrap it with whatever formatting you choose.</i></p><p><b>This
tag is an inline-compatible tag.</b></p></td>
<td class="content_text"><p> block </p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@updated</tt> </p></td>
<td class="content_text"><p><tt>@updated 2003-03-14</tt></p></td>
<td class="content_text"><p>The date at which the header was last updated.</p></td>
<td class="content_text"><p> 1 </p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@version</tt> </p></td>
<td class="content_text"><p><tt>@version 2.3.1</tt></p></td>
<td class="content_text"><p>the version number to which this documentation applies.</p></td>
<td class="content_text"><p> 1 </p></td>
</tr>
</table><br>
<table><p><b><font face="lucida grande, geneva, helvetica, arial, sans-serif" size="2">Listing 2-3 Example
of <tt>@header</tt> 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></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>
<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_2_section_5.html" target="_self">< Previous Page</a><span style="margin-left: 8px"><a href="chapter_2_section_7.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>