chapter_2_section_11.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 Objective-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_1057" title="Tags for Objective-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_10.html" target="_self">< Previous Page</a><span style="margin-left: 8px"><a href="../usage/chapter_3_section_1.html" target="_self">Next Page ></a></span>
</td>
</tr></table>
<hr>
<br><h2>Tags for Objective-C Headers</h2>
<br><h3>Tags
for Objective-C Headers</h3>
<br><h4>Introduction</h4>
<p>HeaderDoc processes a Objective-C header in much the same
way that it does a C header. In fact, until HeaderDoc encounters
a class declaration in an Objective-C header, the processing is
identical. This means you can use any of the tags defined for C
headers within an Objective-C header. See <span class="content_text"><a logicalPath="//apple_ref/doc/uid/TP40001215-CH346-CIHGEIDH" href="chapter_2_section_7.html#//apple_ref/doc/uid/TP40001215-CH346-CIHGEIDH">“Tags Common to All API Types”</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. Within the class
declarations, you can use the <tt>@method</tt> tag
to document each method. Since Objective-C is a superset of C, the
header might also declare types, functions, or other API outside
of any class declaration. You would use <tt>@typedef</tt>, <tt>@function</tt>,
and other C tags to document these declarations.</p>
<br><h5>Processing
Objective-C Classes</h5>
<p>Once HeaderDoc encounters an <tt>@class</tt> tag
(with accompanying declaration) in an Objective-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 an Objective-C header, it creates one frameset for the header
as a whole, and separate framesets for each class declared within
the header.</p>
<br><h5>Processing
Objective-C Protocols</h5>
<p>HeaderDoc processes Objective-C protocol declarations similarly
to class declarations. The documentation for the protocol and the
methods it declares are grouped in their own frameset, which is
accessed from the documentation for the header that contains the protocol.</p>
<br><h5>Processing
Objective-C Categories</h5>
<p>An Objective-C category lets you add methods to an existing
class. When HeaderDoc processes a batch of headers and finds comments
for methods declared in a category, it searches for the associated
class documentation and adds those methods and their documentation
to the class documentation. If the class is not present in the current
batch, HeaderDoc will create a separate frameset of documentation
for the category. </p>
<p>Within a Objective-C class, protocol, or category declaration,
HeaderDoc allows the <tt>@method</tt> tag,
as describe below.</p>
<p> </p>
<br><h4>The
@class, @protocol, and @category Tags</h4>
<p>In Objective-C, class and protocol declarations are quite
similar, and consequently HeaderDoc's <tt>@class</tt> and <tt>@protocol</tt> tags
are parallel in their usage.</p>
<br><h5>Class
and Protocol Tags</h5>
<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>
<tr>
<td class="content_text" scope="row"><p><tt>@category</tt> </p></td>
<td class="content_text"><p>The full name of the category, as declared in the header.
For example, “MyClass(MyCategory)”. HeaderDoc uses the “MyClass”
portion of the name to identify the associated class.</p></td>
<td class="content_text"><p> 1 </p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@protocol</tt> </p></td>
<td class="content_text"><p>The name of the protocol.</p></td>
<td class="content_text"><p> 1 </p></td>
</tr>
</table><br>
<p>Following these tags, you typically provide introductory information
about the purpose of the class, protocol, or category. 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.</p>
<table><p><b><font face="lucida grande, geneva, helvetica, arial, sans-serif" size="2">Listing 2-22 Documentation
tagged as abstract and discussion</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 NSPrinter</code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code> @abstract An NSPrinter object describes a printer's capabilities.</code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code> @discussion An NSPrinter object describes a printer's capabilities, such as whether the printer can print in color and whether it provides a particular font. An NSPrinter object represents... </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>@interface NSPrinter: NSObject <NSCopying, NSCoding></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>@end</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-23 Documentation
included as 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 NSPrinter</code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code> An NSPrinter object describes a printer's capabilities, such as whether the printer can print in color and whether it provides a particular font. An NSPrinter object represents... </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>@interface NSPrinter: NSObject <NSCopying, NSCoding$gt;</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>@end</code></pre></td><td><code><pre></pre></code></td></tr></table></td></tr></table></table>
<br><h5>The
@method Tag</h5>
<p>For methods declared in an Objective-C class, protocol, or
category, use the <tt>@method</tt> tag.</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>@method</tt> </p></td>
<td class="content_text"><p>The method name followed by the description.</p></td>
<td class="content_text"><p> 2 </p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@param</tt> </p></td>
<td class="content_text"><p>The parameter name followed by the description.</p></td>
<td class="content_text"><p> 2 </p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>@result</tt> </p></td>
<td class="content_text"><p>The return value of the method. </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-24 Example
of @method 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>+ (id)dateWithString:(NSString *)description calendarFormat:(NSString *)format;</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) {
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_10.html" target="_self">< Previous Page</a><span style="margin-left: 8px"><a href="../usage/chapter_3_section_1.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>