chapter_7_section_1.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: Symbol Markers for HTML-Based Documentation</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-CH347" title="Symbol Markers for HTML-Based Documentation" turn_anchor="yes"></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> > </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="../config/chapter_6_section_1.html" target="_self">< Previous Page</a><span style="margin-left: 8px"><a href="../classhierarchy/chapter_8_section_1.html" target="_self">Next Page ></a></span>
</td>
</tr></table>
<hr>
<a name="//apple_ref/doc/uid/TP40001215-CH347-BABJIFFD" turn_anchor="no"></a><a name="BABJIFFD" turn_anchor="no"></a><h1 class="page_title">Symbol Markers
for HTML-Based Documentation</h1><p>As HeaderDoc generates documentation for a
set of header files, it injects named anchors (<tt><a
name=”<i>marker</i>”></a></tt>)
into the HTML to mark the location of the documentation for each API
symbol. This document describes the composition of these markers.</p>
<p>As you will see, each marker is self describing and can answer
questions such as:</p>
<ul class="content_text"><li class="content_text">What is the
name of this symbol?</li><br>
<li class="content_text">What type of symbol is this (for example function, typedef,
or method)?</li><br>
<li class="content_text">Which class does this method belong to?</li><br>
<li class="content_text">What is the language environment: C, C++, Java, Objective-C?</li><br></ul>
<p>With this embedded information, the HTML documentation can
be scanned to produce API lists for various purposes. For example,
such a list could be used to verify that all declared API has corresponding
documentation. Or, the documentation could be scanned to produce
indexes of various sorts. The scanning script could as well create
hyperlinks from the indexes to the source documentation. In short,
these anchors retain at least some of the semantic information that
is commonly lost when converting material to HTML format.</p>
<br><h2>The Marker String</h2>
<p>A <b>marker</b> string is defined as:</p>
<p><tt>marker := prefix '/' lang-type '/' sym-type
'/' sym-value</tt></p>
<p>A marker is a string composed of two or more values separated
by a forwars slash (<tt>/</tt>).
The forward-slash character is used because it is not a legal character
in the symbol names for any of the languages currently under consideration.</p>
<p>The prefix defines this marker as conforming to our conventions
and helps identify these markers to scanners. The language type
defines the language of the symbol. The symbol type defines some
semantic information about the symbol, such as whether it is a class name
or function name. The symbol value is a string representing the
symbol.</p>
<p>Because the string must be encoded as part of a URL, it must
obey a very strict set of rules. Specifically, any characters other
than letters and numbers must be encoded as a URL entity. For example,
the operator <tt>+</tt> in C++
would be encoded as <tt>%2b</tt>.</p>
<p>By default, the prefix is <tt>However, the prefix string can be changed using HeaderDoc's configuration
file.</p>
<p>The currently-defined language types are described in <span class="content_text"><a logicalPath="//apple_ref/doc/uid/TP40001215-CH347-CIHDGCAD" href="chapter_7_section_1.html#//apple_ref/doc/uid/TP40001215-CH347-CIHDGCAD">Table A-1</a></span>.</p>
<a name="//apple_ref/doc/uid/TP40001215-CH347-CIHDGCAD" turn_anchor="no"></a><a name="CIHDGCAD" turn_anchor="no"></a><b><font face="lucida grande, geneva, helvetica, arial, sans-serif" size="2">Table A-1 HeaderDoc API reference language types</font></b><br><br><table border = "1" cellpadding = "3">
<tr>
<td class="content_text" scope="row"><p><tt>c</tt></p></td>
<td class="content_text"><p>C</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>occ</tt></p></td>
<td class="content_text"><p>Objective-C</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>java</tt></p></td>
<td class="content_text"><p>Java</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>javascript</tt></p></td>
<td class="content_text"><p>JavaScript</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>cpp</tt></p></td>
<td class="content_text"><p>C++</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>php</tt></p></td>
<td class="content_text"><p>PHP</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>pascal</tt></p></td>
<td class="content_text"><p>Pascal</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>perl</tt></p></td>
<td class="content_text"><p>perl script</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>shell</tt></p></td>
<td class="content_text"><p>Bourne, Korn, Bourne Again, or C shell script</p></td>
</tr>
</table><br>
<p>The language type defines the language binding of the symbol.
Some logical symbols may be available in more than one language.
The <tt>c</tt> language defines
symbols which can be called from the C family of languages (C, Objective-C,
and C++).</p>
<br><h3>Symbol Types for All Languages</h3>
<p>The symbol types common to all languages are described in <span class="content_text"><a logicalPath="//apple_ref/doc/uid/TP40001215-CH347-CIHJEFGJ" href="chapter_7_section_1.html#//apple_ref/doc/uid/TP40001215-CH347-CIHJEFGJ">Table A-2</a></span>.</p>
<a name="//apple_ref/doc/uid/TP40001215-CH347-CIHJEFGJ" turn_anchor="no"></a><a name="CIHJEFGJ" turn_anchor="no"></a><b><font face="lucida grande, geneva, helvetica, arial, sans-serif" size="2">Table A-2 Symbol types for all languages</font></b><br><br><table border = "1" cellpadding = "3">
<tr>
<td class="content_text" scope="row"><p>tag</p></td>
<td class="content_text"><p>struct, union, or enum tag</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>econst</tt></p></td>
<td class="content_text"><p>an enumerated constant—that is, a symbol defined inside
an enum</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>tdef</tt></p></td>
<td class="content_text"><p>typedef name (or Pascal <tt>type</tt>)</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>macro</tt></p></td>
<td class="content_text"><p>macro name (without '()')</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>data</tt></p></td>
<td class="content_text"><p>global or file-static data</p></td>
</tr>
<tr>
<td class="content_text" scope="row"><p><tt>func</tt></p></td>
<td class="content_text"><p>function name (without '()')</p></td>
</tr>
</table><br>
<br><h3>Symbol Types for Languages
With Classes</h3>
<dl class="content_text"><br><dt class="content_text"><tt>cl</tt></dt>
<dd class="content_text">class name</dd>
<br><dt class="content_text"><tt>intf</tt></dt>
<dd class="content_text">interface or protocol name</dd>
<br><dt class="content_text"><tt>cat</tt></dt>
<dd class="content_text">category name, just for Objective-C</dd>
<br><dt class="content_text"><tt>intfm</tt></dt>
<dd class="content_text">method defined in an interface (or protocol)</dd>
<br><dt class="content_text"><tt>instm</tt></dt>
<dd class="content_text">an instance method 'clm' a class (or static [in java
or c++]) method</dd></dl>
<br><h3>C++ (cpp) Symbol Types</h3>
<dl class="content_text"><br><dt class="content_text"><tt>tmplt</tt></dt>
<dd class="content_text">C++ class template</dd>
<br><dt class="content_text"><tt>ftmplt</tt></dt>
<dd class="content_text">C++ function template</dd>
<br><dt class="content_text"><tt>func</tt></dt>
<dd class="content_text">C++ scoped function (i.e. not extern 'C'); includes
return type and signature.</dd></dl>
<br><h3>Java (java) Symbol Types</h3>
<dl class="content_text"><br><dt class="content_text"><tt>clconst</tt></dt>
<dd class="content_text">Java constant values defined inside a class</dd></dl>
<div class="notebox"><span class="content_text"><b>Note: </b>The
symbol value for method names includes the class name. </span></div>
<br><h3>Objective-C (occ) Method Name
Format</h3>
<p>The format for method names for Objective-C is:</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>class_name '/' method_name</code></pre></td><td><code><pre></pre></code></td></tr><tr><td scope="row"><pre><code>e.g.: //apple_ref/occ/instm/NSString/stringWithCString: </code></pre></td><td><code><pre></pre></code></td></tr></table></td></tr></table></table>
<p>For methods in Objective-C categories, the category name is <i>not</i> included
in the method name marker. The class named used is the class the
category is defined on. For example, for the windowDidMove: delegate
method on in NSWindow, the marker would be:</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>e.g.: //apple_ref/occ/intfm/NSObject/windowDidMove:</code></pre></td><td><code><pre></pre></code></td></tr></table></td></tr></table></table>
<br><h3>C++/Java (cpp/java) Method
Name Format</h3>
<p>The format for method names for Java and C++ is:</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> class_name '/' method_name '/' return_type '/' '(' signature ')' e.g.: //apple_ref/java/instm/NSString/stringWithCString/NSString/(char*) </code></pre></td><td><code><pre></pre></code></td></tr></table></td></tr></table></table>
<p>For Java and C++, signatures are part of the method name;
signatures are enclosed in parentheses. The algorithm for encoding
a signature is:</p>
<ol class="content_text"><li class="content_text">Remove the
parameter name ; for example, <tt>change (Foo *bar,
int i)</tt> to <tt>(Foo *, int
)</tt>.</li><br>
<li class="content_text">Remove spaces ; for example, change <tt>(Foo
*, int )</tt> to <tt>(Foo*,int)</tt>.</li><br></ol>
<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="../config/chapter_6_section_1.html" target="_self">< Previous Page</a><span style="margin-left: 8px"><a href="../classhierarchy/chapter_8_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>