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 (Objective-C only).

cl

Class name.

Note: In Perl, this is used for the names of packages, and thus the names may contain a double colon between parts of package names. For example:

//apple_ref/perl/cl/HeaderDoc::APIOwner

clconst

Constant values defined inside a class. For example:

//apple_ref/java/clconst/ClassName/kConstantName

clm

Class (or static [in java or c++]) method.

Note: The formats for method names are described in Objective-C (occ) Method Name Format and C++/Java (cpp/java) Method Name Format.

data

Instance data. For example:

//apple_ref/cpp/data/MyClass/MyVariable

intf

Interface or protocol name.

intfcm

Class method defined in a protocol

Note: The formats for method names are described in Objective-C (occ) Method Name Format and C++/Java (cpp/java) Method Name Format.

intfm

Method defined in an interface (or protocol).

Note: The formats for method names are described in Objective-C (occ) Method Name Format and C++/Java (cpp/java) Method Name Format.

intfp

Property defined in an interface (or protocol)

//apple_ref/occ/intfp/ClassName/PropertyName

instm

Instance method.

Note: The formats for method names are described in Objective-C (occ) Method Name Format and C++/Java (cpp/java) Method Name Format.

instp

Instance property. For example:

//apple_ref/occ/instp/ClassName/PropertyName

C++ (cpp) Symbol Types

tmplt

C++ class template.

ftmplt

C++ function template.

Note: The format for this type is described in C++/Java (cpp/java) Method Name Format.

func

C++ scoped function (in other words, not extern 'C'); includes return type and signature as described in C++/Java (cpp/java) Method Name Format, but with no class name. For example:

//apple_ref/cpp/func/funcName/returnType/(argType,argType,argType)

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 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

Special API Reference Types in the doc Hierarchy

In general, the doc hierarchy should be considered to be an opaque blob of content. You should not count on the structure of a doc API reference. However, there are a few special subtypes within the doc space that are significant and should be used only for the stated purpose.

• uid—A unique identifier for a document. You may use values generated by uuidgen here. All other values are reserved for use by Apple.

• title:...—A HeaderDoc-specific hierarchy for special identifiers generated from the name portion of a HeaderDoc comment. These are generated when:

  • A name is specified in the HeaderDoc comment that does not match any parsed name.

  • A declaration is parsed that has no name (such as an anonymous enumeration) and the specified name contains spaces or other illegal characters.

  The complete name for this reference part depends on the name of the original data type. For example, a typedef would be:

  //apple_ref/doc/title:tdef/Whatever

  Most of the time, if you see these in HeaderDoc output, it means that the name specified in a HeaderDoc comment is wrong.

• enumconstant, functionparam, methodparam, defineparam, structfield, typedeffield—Special reference types for fields within structures, parameters within functions, and so on. Appears at the relevant point in the documentation.

  These are rarely useful, but can be used in cases where, for example, a function has numerous parameters to link to a specific parameter in the list.

  The enumconstant field should only appear if a normal API reference marker (econst) does not, which means you are unlikely to actually see this marker type in practice.

• anysymbol—Valid in link requests only. A link request in this namespace causes the link resolver to look up the symbol by name instead of by API reference. For example, the link request:

  //apple_ref/doc/anysymbol/MyProject

  would match any of the following API references:

  //apple_ref/c/func/MyProject

  //apple_ref/cpp/instm/MyClass/MyProject/bool/(char*,int)

  //apple_ref/perl/data/MyProject

  //apple_ref/java/cl/MyProject

  And so on. If more than one of these symbols exists, it matches the nearest symbol in the hierarchy (as determined by the number of leading absolute path parts).

Resolving Conflicting API References

In general, API references should not conflict. However, if two symbols with identical names and types occur in different namespaces, it is possible to have a conflict when you link together documentation that contains both namespaces.

When this occurs, HeaderDoc makes a best effort attempt at choosing the right match. For each potential link destination, HeaderDoc examines the path of the file containing that anchor and counts the number of leading path parts that match between that path and the path of the file that contains the link request. Then, HeaderDoc chooses the destination with the most matching path parts. (In the event of a tie, HeaderDoc typically chooses the first destination parsed, but you should not count on this ordering.)

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.

  Note: This configuration file is read by gatherHeaderDoc, not by resolveLinks. Thus, this configuration file setting affects the behavior of resolveLinks only when resolveLinks is run by gatherHeaderDoc, not when you run resolveLinks manually.

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 for later use.

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.

Beginning in HeaderDoc 8.8, resolveLinks supports additional flags to take advantage of these cross-reference files. Typically, you would use some combination of the -s, -S, -b, and -i flags.

These three flags are interrelated in subtle ways. The purpose of the complexity is so that you can construct links between two folders in such a way that the links will be valid after the folders are put into their final location. To that end, the flags provide prefix stripping and prepending.

It is easiest to explain these flags by providing an example of a common use case. You have two directories, A and B.

To create these links, you would first generate cross-reference files for each folder like this:

resolveLinks -n -x /tmp/A.xrefs -b "$PWD/" "A"

resolveLinks -n -x /tmp/B.xrefs -b "$PWD/" "B"

The paths in the resulting cross-reference file are in the form A/... or B/....

Next, you must actually resolve the links. This is where the other flags come into play.

resolveLinks -b "$PWD/" -s /tmp/B.xrefs -S "/Library/WebServer/Documents/Utilities/" -i "/Library/WebServer/Documents/Tools/" "A"

resolveLinks -b "$PWD/" -s /tmp/A.xrefs -S "/Library/WebServer/Documents/Tools/" -i "/Library/WebServer/Documents/Utilities/" "B"

You can pass in multiple pairs of -s and -S flags (up to a maximum of 1024) for additional flexibility. For each seed file, you must first use the -s flag to specify the location of the seed file itself, then use the -S flag to specify the location where the content described by that seed file will eventually be installed.

In addition to seed file paths, you should also use the -i flag to tell resolveLinks where the folder you are processing will eventually be installed. Note that as before, the -b flag determines what portion to strip from each path in the folder you are processing, and that the trailing slash in the -b flag is significant here as well.

In effect, you can think of the flags like this:

• -b—Strips off leading path parts from the folder you are currently processing. The last path part is stripped only if followed by a trailing slash.

• -i—Adds leading path parts to the folder you are currently processing (representing the proposed final install location).

• -S—Adds leading path parts to folders processed previously and imported from a seed file (representing their proposed final install locations).

Finally, if desired, you can pass the -a flag to tell resolveLinks to use absolute paths instead of relative paths when linking to the content described by a particular seed file or by all seed files. Like the -S flag, if passed before the first -s flag, the -a flag modifies the linking behavior globally. Otherwise, it modifies only the linking behavior for the preceding -s flag.

For more information, see the manual page for resolveLinks.