<html> <head> <title>Symbol Markers for HTML-based Documentation</title> </head> <body bgcolor="white"> <a href="HeaderDoc.html">[Overview]</a> <h1>Symbol Markers for HTML-based Documentation</h1> <h2>Introduction</h2> <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: <ul> <li>What is the name of this symbol?</li> <li>Is this a function, typedef, method, etc.?</li> <li>Which class does this method belong to?</li> <li>What is the language environment: C, C++, Java, Objective-C?</li> </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> <h2><font face="Times"><b>The Marker String</b></font></h2> <p><font face="Times">A <b>marker</b> string is defined as:</font></p> <p><font face="Times"><tt>marker := prefix '/' lang-type '/' sym-type '/' sym-value</tt></font></p> <p><font face="Times">A marker is a string composed of 4 values separated by '/'. The forward-slash character is used because it is not a legal character in the symbol names for any of the languages we are considering. 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 (e.g. whether it is a class name or function). The symbol value is a string representing the symbol.</font></p> <p><font face="Times"><b>By default, the prefix is:</b> </font></p> <p><font face="Times"><tt>'//apple_ref'</tt></font></p> <p>However, the prefix string can be reassigned using HeaderDoc's configuration file.</p> <p><font face="Times"><b>The language types are:</b></font></p> <pre> 'c' C 'occ' Objective-C 'java' Java 'cpp' C++</pre> <p> <font face="Times">The language type defines the language binding of the symbol. Some logical symbols may be available in more than one language. The 'c' language defines symbols which can be called from the C family of languages (C, Objective-C, and C++).</font></p> <p><font face="Times"><b>Symbol types for for the 'c' lang:</b></font></p> <pre> sym-type notes -------- --------- 'tag' "tag": struct, union, or enum tag 'econst' "enumerated constant": symbols defined inside an enum 'tdef' typedef name 'macro' macro name (without '()') 'data' global or file-static data 'func' function name (without '()')</pre> <p> <font face="Times" size="3"><b>Symbol types for for the languages 'occ', 'java', 'cpp'</b></font></p> <pre> sym-type notes -------- --------- 'cl' class name 'intf' interface or protocol name 'cat' category name, just for Objective-C 'intfm' method defined in an interface (or protocol) 'instm' an instance method 'clm' a class (or static [in java or c++]) method</pre> <p> <font face="Times"><b>Symbol types for for the language 'cpp'</b></font></p> <pre> sym-type notes -------- --------- 'tmplt' C++ class template 'ftmplt' C++ function template 'func' C++ scoped function (i.e. not extern 'C'); includes return type and signature.</pre> <p> </p> <p><font face="Times"><b>Symbol types for for the language 'java'</b></font> <pre> sym-type notes -------- --------- 'clconst' Java constant values defined inside a class</pre> <p><font face="Times">The symbol value for method names includes the class name. </font></p> <p> </p> <p><font face="Times"><b>The format for method names for Objective-C is: </b></font> <pre> class_name '/' method_name e.g.: //apple_ref/occ/instm/NSString/stringWithCString: </pre> <p><font face="Times">For methods in Objective-C categories, the category name is <b>not</b> 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:</font></p> <pre> e.g.: //apple_ref/occ/intfm/NSObject/windowDidMove:</pre> <p> </p> <font face="Times"><b>The format for method names for Java and C++ is:</b></font> <pre> class_name '/' method_name '/' return_type '/' '(' signature ')' e.g.: //apple_ref/java/instm/NSString/stringWithCString/NSString/(char*) </pre> <p><font face="Times">For Java and C++, signatures are part of the method name; signatures are enclosed in parens. The algorithm for encoding a signature is:</font></p> <ol> <li><font face="Times" size="3">Remove the parameter name e.g. (Foo *bar, int i) -> (Foo *, int )</font> <li><font face="Times" size="3">Remove spaces e.g. (Foo *, int ) -> (Foo*,int)</font> </ol> </body> </html>