Symbol Markers for HTML-Based Documentation

As HeaderDoc generates documentation for a set of header files, it injects named anchors (<a name="marker"></a>) into the HTML to mark the location of the documentation for each API symbol. This document describes the composition of these markers.

As you will see, each marker is self describing and can answer questions such as:

• What is the name of this symbol?

• What type of symbol is this (for example function, typedef, or method)?

• Which class does this method belong to?

• What is the language environment: C, C++, Java, Objective-C?

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.

The Marker String

A marker string is defined as:

marker := prefix '/' lang-type '/' sym-type '/' sym-value

A marker is a string composed of two or more values separated by a forward slash (/). 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.

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.

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 + in C++ would be encoded as %2b.

By default, the prefix is //apple_ref. However, the prefix string can be changed using HeaderDoc's configuration file.

The currently-defined language types are described in Table B-1.

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++).

Symbol Types for All Languages

The symbol types common to all languages are described in Table B-2.

Symbol Types for Languages With Classes

cat

category name, just for Objective-C

cl

class name

clm

class (or static [in java or c++]) method

intf

interface or protocol name

intfcm

class method defined in a protocol

intfm

method defined in an interface (or protocol)

intfp

property defined in an interface (or protocol)

instm

instance method

instp

instance property

C++ (cpp) Symbol Types

tmplt

C++ class template

ftmplt

C++ function template

func

C++ scoped function (i.e. not extern 'C'); includes return type and signature.

Java (java) Symbol Types

clconst

Java constant values defined inside a class

Objective-C (occ) Method Name Format

The format for method names for Objective-C is:

class_name '/' method_name

e.g.: //apple_ref/occ/instm/NSString/stringWithCString:

For methods in Objective-C categories, the category name is not 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:

e.g.: //apple_ref/occ/intfm/NSObject/windowDidMove:

Objective-C Property Format

The format for an Objective-C protocol is:

class_name '/' protocol_name

e.g. //apple_ref/occ/instp/MyClass/MyProp

C++/Java (cpp/java) Method Name Format

The format for method names for Java and C++ is:

    class_name '/' method_name '/' return_type '/' '(' signature ')'

e.g.: //apple_ref/java/instm/NSString/stringWithCString/NSString/(char*)

For Java and C++, signatures are part of the method name; signatures are enclosed in parentheses. The algorithm for encoding a signature is:

1. Remove the parameter name; for example, change (Foo *bar, int i) to (Foo *, int ).

2. Remove spaces; for example, change (Foo *, int ) to (Foo*,int).

Interface Builder Bindings Format

The format for Interface Builder bindings is:

'binding' '/' class_name '/' binding_name

e.g. //apple_ref/occ/binding/myclass/mybinding

Using resolveLinks to Resolve Cross References

HeaderDoc includes a tool called resolveLinks (in /System/Library/Perl/Extras/5.8.6/HeaderDoc/bin) that is used for resolving cross-references for you Wherever a cross-reference appears, a link is generated if the destination exists.

The resolveLinks tool processes an entire tree of content in two passes. In the first pass, it locates destination anchors. These destination anchors look like this:

<a name="//apple_ref/..."></a>

Each of these name values is an identifier for an API symbol. The format for these identifiers is specified in “The Marker String.”

In the second pass, resolveLinks searches for cross-references to these destinations. These cross-references can occur in one of two forms, depending on whether a destination is known to exist or not.

<a href="path">foo</a>

<!-- a -->

Each of these logicalPath values is then paired (if possible) with name values obtained during the first pass. If a destination exists for a cross-reference, resolveLinks inserts the relative path of the destination anchor in the cross-reference request’s href attribute. The result is that the cross-reference anchor is now a valid link to the requested destination anchor.

If the link exists and the cross-reference request is in the form of a comment, the resolveLinks tool changes the cross-reference request from a comment into an anchor (link) tag. Similarly, if the destination does not exist, it changes the cross-reference from an anchor tag to a comment tag. The result is that there should never be any broken links.

For the most part, this process is transparent to you as a user. There are two exceptions, however: cross-references between document sets and cross-references using multiple API reference prefixes (such as apple_ref).

Using Multiple API Reference Prefixes

If you use multiple API reference prefixes in a single tree of output content and want to link it together using resolveLinks, you must tell resolveLinks to look for all of the prefixes you care about. There are two ways to do this:

• Run resolveLinks manually, specifying the -r flag for each prefix. For example:

  resolveLinks -r david_ref -r joe_ref /path/to/dir

• Specify a list of valid prefixes in your headerDoc2HTML.config file using the externalAPIUIDPrefixes option.

Using External Cross-Reference Files

Whenever resolveLinks processes a tree, it generates a cross-reference file for that content. By default, it saves this file as /tmp/xref_out, but you can change this with the -x flag.

If you want to process a tree in read-only mode (without writing back changes to the tree itself), you can specify the -n (no write) flag. In this mode, it will generate a cross-reference output file, but will not modify the HTML input files.