HeaderDoc Unfettered: Symbol Markers for HTML-based Documentation

# 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?
- Is this a function, typedef, method, etc.?
- 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 '/'. 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, 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:

c
  C
occ
  Objective-C
java
  Java
javascript
  JavaScript
cpp
  C++
php
  PHP
pascal
  Pascal
perl
  perl
shell
  Bourne, Korn, Bourne Again, or C shell script

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:

tag
  struct, union, or enum tag
econst
  an enumerated constant—that is, a symbol defined inside an enum
tdef
  typedef name
macro
  macro name (without '()')
data
  global or file-static data
func
  function name (without '()')

### Symbol Types for Languages with Classes

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

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

Note: The symbol value for method names includes the class name.

### 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:
| `
`

### 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 parens. The algorithm for encoding a signature is:

1. Remove the parameter name , e.g. (Foo *bar, int i) -> (Foo *, int )
2. Remove spaces , e.g. (Foo *, int ) -> (Foo*,int)

© 1999, 2004 Apple Computer, Inc. All Rights Reserved. (Last updated: 2004-05-27)