HeaderDoc::HeaderElement

Declared In:

Introduction

Base class for all API objects.

Discussion

The HeaderElement class is the base class for all objects representing API elements, including headers, structs, functions, classes, etc. The majority of HeaderDoc classes are subclasses of this class.

This class provides services common to all API elements (or services common to several elements). The most important functions in this class are:

processComment: Parses a HeaderDoc comment block.
declarationInHTML: Returns the declaration in HTML/XML by calling into the ParseTree class.
documentationBlock and XMLdocumentationBlock: Return the entire documentation output for this object (class, function, enumeration, data structure, and so on) and any descendants enclosed within it.
keywords: Returns a set of keywords for parsing declarations in the current programming language and returns whether those keywords should be interpreted in a case-sensitive or case-insensitive fashion.
apirefSetup: Does a lot of the work setting up the API reference for this object and its subclasses.
apiref and apiuid: Get and set the API reference, respectively.

This API object type should never actually be emitted as output; only its subclasses are relevant.

Member Functions

_getDoxyTagString: Gets a Doxygen-style tag string for this object.
_initialize: Initializes an instance of a HeaderElement object.
abstract: Gets/sets the abstract.
accessControl: Gets/sets the access control (public/private) for this object.
addConstant: Adds a constant to the array of constants associated with an object.
addParsedParameter: Adds a parsed parameter to the array of parsed parameters associated with a function, etc.
addParseTree: Adds a parse tree to the array of parse trees associated with this object.
addTaggedParameter: Adds a tagged parameter to the array of tagged parameters associated with a function, etc.
addToCleanup: Adds a name to the PARSETREECLEANUP array.
addToFields: Adds a field to the array of fields associated with an object.
addToIncludedDefines: Adds a #define to the array of #define macros associated with a defineblock declaration.
addToNameRefs: Adds a name to the NAMEREFS array.
addVariable: Adds a variable to the array of local variables associated with a function, etc.
apiOwner: Gets/sets the API owner for this object.
apiref: Generates the API ref (apple_ref) for a function, data type, etc.
apiRefLanguage: Returns the language token that should appear in an API reference.
apirefSetup: Collects data for generating the API ref (apple_ref) for a function, data type, etc.
apiuid: Sets the apple_ref ID for a data type, function, etc.
apiuidname: Returns the name of an API element for UID purposes.
appleRefIsDoc: Sets or gets a state flag.
attribute: This function adds an attribute for a class or header.
attributelist: Add an attribute list.
autoRelate: Maintains the list of auto-related references used for mixed group handling.
availability: Gets/sets the availability for this object.
availabilityAuto: Appends an availabiilty macro string to the original availability string if it is missing.
blockoffset: The line number of the start of the block containing a declaration.
checkAttributeLists: Returns the value of an attribute list whose name matches the one passed in.
checkShortLongAttributes: Returns the value of an attribute in the object's long or short attributes whose name matches the one passed in.
class: The HeaderDoc class for this object.
clearGroup: Clears the group for this object.
clone: Duplicates this HeaderElement object into another one.
compositePageUID: Returns a UID suitable for a composite page (when classAsComposite is 0).
constants: Gets/sets the array of constants associated with an APIOwner, Enum, etc.
constructor_or_destructor: Returns whether the current function is a constructor or destructor.
dbprint: Prints this object for debugging purposes.
dbprint_expanded: Prints a variable (e.g. an array) in detail for debugging purposes.
declaration: Gets/sets the vestigial text declaration.
declarationInHTML: Prints the declaration with HTML or XML formatting.
declaredIn: Returns the "Declared in" HTML string for a class.
DESTROY: Helper called by Perl when this object gets freed.
discussion: Gets/sets the discussion value.
discussion_set: Returns true if the discussion is set explicitly with an @discussion tag.
discussion_sub: Gets the discussion value (private function).
discussionLocked: Stores a backup copy of the abstract and discussion for later use or checks to see if one has been stored.
documentationBlock: Returns the documentation output for this object (in HTML).
doExternalStyle: Returns a string of HTML <link> tags for multiple external stylesheets.
dropParsedParameter: Deletes the last parsed parameter added to this object.
encoding: Returns the character set encoding of the enclosing file.
filename: Gets/sets the filename for a header file.
firstconstname: Gets/sets the name of the first constant in an enumeration.
fixParseTrees: Adds the main parse tree to the parse tree list if missing.
fixup_inheritDoc: HTML/XML fixup code to insert superclass discussions
fixup_values: HTML/XML fixup code to insert values
fixupParsedParameters: Searches for a parameter in the parsed parameters list. Also takes additional parsed parameters from enclosed structures and adds them to the outer typedef object.
free: Attempts to detach this object and destroy references to it to release memory.
fullpath: Gets/sets the full path to a header file.
functionContents: Gets/sets the function body for a function.
generateLinkUID: Generates a special UID for inherited content
genRef: Generate a cross-reference request
genRefCore: Generate a cross-reference request
genRefFromDeclaration: Generate a cross-reference request (from a declaration)
genRefHTML: Generate a cross-reference request in HTML style
genRefSub: Constructs an API reference from its constituent parts.
getAttributeLists: Returns the attribute lists for this object.
getAttributes: Returns the attributes for this object, formatted in HTML for output.
getDoxyKind: Returns this object's tag type for use in Doxygen-style tag files.
getMethodType: Returns the method type portion of the API reference for a C++ method.
getStyle: Returns the CSS style data for the specified name.
group: Gets/sets the group for this object and adds it to the group object.
halfbaked_discussion: Returns the discussion (without nameline discussion).
headerDocMark: Returns a custom HeaderDoc doc navigator comment for this object.
headerDump: Prints a dump of function and #define declarations in this header for debugging purposes.
hideContents: Gets/sets whether this object's contents should be hidden.
htmlToXML: Converts HTML to XHTML (fast version).
inDefineBlock: Gets/sets whether this object is a member of a define block.
indexgroup: Sets the index group for a class or header.
inheritDoc: Parent discussion for inheritance
isAPIOwner: Returns whether this is an API owner (class, header, etc.)
isBlock: Gets/sets whether this object is a block declaration.
isCallback: Gets/sets whether this is a callback.
isFramework: Returns whether this is a framework object.
isFunctionPointer: Gets/sets whether this object is a function pointer.
isInternal: Gets/sets the ISINTERNAL flag.
isTemplate: Gets/sets whether this is a template function/class.
keywords: Returns all known keywords for the current language.
lang: Gets/sets the programming language for this object.
linenum: The line number where a declaration began.
linenuminblock: The line number where a declaration began relative to the block.
linkageState: Gets/sets the linkage state for this object.
linkfix: Retargets HTML links.
listfixup: Converts numbered lists in comments into HTML ordered list tags where possible.
masterEnum: Gets/sets whether this array is the "master" enum.
mediumrarename: Returns the "medium rare" name.
name: Gets/sets the name of this function/var/class/*.
nameline_discussion: Gets/sets the nameline discussion.
namespace: Sets and returns the namespace of this class.
new: Creates a new HeaderElement object.
noRegisterUID: Gets/sets whether this object should be banned from UID registration.
origClass: Gets/sets the original class info.
origType: Gets/sets type conversion history.
outputformat: Gets/sets the output format (html, xml).
paramMatching: The guts of taggedParamMatching and parsedParamMatching.
parsedParamCompare: Compares the parsed parameters of two methods.
parsedParameters: Gets/sets the parsed parameters list for a function, etc.
parsedParamMatching: Checks fr a parsed parameter matching a given name.
parserState: Gets/sets the parser state.
parseTree: Gets/sets the parse tree associated with this object.
parseTreeList: Returns the array of parse trees associated with this object.
prepareDiscussionForTemporary: Wipes the discussion and abstract so that defines in a @defineblock can be correctly parsed.
preserve_spaces: Gets/sets whether spaces in the declaration should be preserved.
printObject: Prints this object for debugging purposes.
privateDeclaration: Gets/sets the prvate declaration for a C++ method.
processComment: Processes a HeaderDoc comment.
raw_discussion: Returns the discussion without merging in the name line.
raw_nameline_discussion: Returns the nameline discussion by itself.
rawname: Returns the "raw" name.
rawname_extended: Returns the "raw" name.
requestedUID: Sets an override API uid for the rare cases where they would conflict by nature.
result: Gets/sets the result (return values) text for functions, Objective-C methods, function-like macros, structures containing callbacks, type definitions containing callbacks, and Objective-C properties. etc.
returntype: Gets/sets the return type for this object.
see: Add see/seealso (JavaDoc compatibility enhancement)
seeDupCheck: Gets/sets the SEEALSODUPCHECK value.
setAPIOBackReferences: Clears references to higher nodes in the object graph.
setStyle: Sets the CSS for a particular style name.
splitmerge: Merges newlines and carriage returns with preceding text, but only if nonsequential.
strcasecmp: Compares two strings in a case-insensitive fashion.
strdate: A function for converting numeric dates into strings.
styleSheet: Returns the complete CSS stylesheet for HeaderDoc content.
sublang: Gets/sets the programming language dialect for this object.
suppressChildren: Gets/sets whether this object's children should be suppressed.
taggedParameters: Gets/sets the tagged parameters list for a function, etc.
taggedParamFind: Finds a tagged parameter by name.
taggedParamMatching: Checks fr a tagged parameter matching a given name.
taggedParsedCompare: Compares tagged parameters to parsed parameters (for validation)
tagNameRegexpAndSuperclassFieldNameForType: Returns HeaderDoc tag names and English names for a given HeaderDoc object.
textToXML: Encodes text into HTML/XML entities.
throws: Gets/sets the list of exceptions thrown by this class/function.
typedefContents: Gets/sets the contents of a simple typedef.
unlockDiscussion: Restores a backup copy of the abstract and discussion stored by discussionLocked.
unregister: Unregisters this object.
updated: Gets/sets the last updated date for this object.
use_stdout: Gets/sets the USESTDOUT flag (0/1).
value: Value for constants, variables, etc.
variables: Gets/sets the array of local variables associated with a function, etc.
wipeUIDCache: Wipes any cached API and/or link UIDs for this object.
XMLabstract: Returns the abstract for XML use.
XMLdiscussion: Returns the discussion formatted for XML.
XMLdocumentationBlock: Returns the documentation output for this object (in XML).
XMLthrows: Returns the list of exceptions thrown by this class/function.

_getDoxyTagString

Gets a Doxygen-style tag string for this object.

sub _getDoxyTagString

Parameters

self: This object.
prespace: Leading whitespace to prepend to each line.

_initialize

Initializes an instance of a HeaderElement object.

sub _initialize

Parameters

self: The object to initialize.

abstract

Gets/sets the abstract.

sub abstract

Parameters

self: The current object.
throws: The new value. (Optional.)
isbrief: Use for compatibility the Doxygen @brief tag. Pass 1 for the @brief behavior (abstract is limited to one paragraph of content, so everything after a gap becomes part of the discussion), 0 for the normal @abstract behavior.

accessControl

Gets/sets the access control (public/private) for this object.

sub accessControl

Parameters

self: This object.
access: The new value. (Optional.)

addConstant

Adds a constant to the array of constants associated with an object.

sub addConstant

Parameters

self: This object.
constants: An array of constants to add.

addParsedParameter

Adds a parsed parameter to the array of parsed parameters associated with a function, etc.

sub addParsedParameter

Parameters

self: The (generally Function) object.
parsedParam: An array of parsed parameters to add.

Discussion

The parsed parameters list is an array of MinorAPIElement objects that represent the parameters as parsed from the actual declaration. Not all languages support parameter name parsing. (For example, Perl does not.)

addParseTree

Adds a parse tree to the array of parse trees associated with this object.

sub addParseTree

Parameters

self: This object.
tree: A reference to the parse tree object to add.

addTaggedParameter

Adds a tagged parameter to the array of tagged parameters associated with a function, etc.

sub addTaggedParameter

Parameters

self: The (generally Function) object.
taggedParms: An array of tagged parameters to add.

Discussion

The tagged parameters list is an array of MinorAPIElement objects that represent the parameters as tagged in the HeaderDoc comment block.

addToCleanup

Adds a name to the PARSETREECLEANUP array.

sub addToCleanup

Discussion

In BlockParse.pm, HeaderDoc sets the owner of a parse tree to an API object. If that object goes away, that association needs to be cleared. This array keeps track of that.

addToFields

Adds a field to the array of fields associated with an object.

sub addToFields

Parameters

self: This object.
fields: An array of fields to add.

addToIncludedDefines

Adds a #define to the array of #define macros associated with a defineblock declaration.

sub addToIncludedDefines

Parameters

self: The (generally PDefine) object.
defines: An array of macros to add.

addToNameRefs

Adds a name to the NAMEREFS array.

sub addToNameRefs

Discussion

In BlockParse.pm, HeaderDoc adds each object into the associative array HeaderDoc::namerefs. Because Perl's garbage collection is a joke, this reference must be destroyed to free the object.

addVariable

Adds a variable to the array of local variables associated with a function, etc.

sub addVariable

Parameters

self: The (generally Function) object.
variables: An array of variables to add.

apiOwner

Gets/sets the API owner for this object.

sub apiOwner

Parameters

self: This object.
owner: The APIOwner object to set as this object's API owner.

apiref

Generates the API ref (apple_ref) for a function, data type, etc.

sub apiref

Parameters

self: This object.
composite: Set to 1 for the composite page (if classAsComposite is not 1), else 0.

apiRefLanguage

Returns the language token that should appear in an API reference.

sub apiRefLanguage

Parameters

self: The current object.
lang: The raw HeaderDoc (internal) language name.

apirefSetup

Collects data for generating the API ref (apple_ref) for a function, data type, etc.

sub apirefSetup

Discussion

See apiref for the actual generation.

apiuid

Sets the apple_ref ID for a data type, function, etc.

sub apiuid

Parameters

obj: The object for which you want ot generate an API ref.

Discussion

The actual API ref eneration occurs in apirefSetup.

apiuidname

Returns the name of an API element for UID purposes.

sub apiuidname

appleRefIsDoc

Sets or gets a state flag.

sub appleRefIsDoc

Parameters

value

Discussion

The APPLEREFISDOC state flag controls whether to use a language-specific or doc-specific apple_ref marker for a doc block.

attribute

This function adds an attribute for a class or header.

sub attribute

Parameters

name: The name of the attribute to be added
attribute: The contents of the attribute
long: 0 for single line, 1 for multi-line.

attributelist

Add an attribute list.

sub attributelist

Parameters

name: The name of the list
attribute: A string in the form "term description..." containing a term and description to be inserted into the list named by name.

autoRelate

Maintains the list of auto-related references used for mixed group handling.

sub autoRelate

Discussion

When you have a mixed block containing functions and defines, the INCLUDED_DEFINES array ceases to be a workable way to find out what is in that block. This function stores and retrieves an array containing only the API references (UIDs) for machine-generated "See Also" cross-references.

availability

Gets/sets the availability for this object.

sub availability

Parameters

self: This object.
availstring: The availability string from the HeaderDoc comment.

availabilityAuto

Appends an availabiilty macro string to the original availability string if it is missing.

sub availabilityAuto

Parameters

self: This object.
orig: The original availability string.

blockoffset

The line number of the start of the block containing a declaration.

sub blockoffset

Discussion

We don't want to show this, so we can't use an attribute. This is private.

checkAttributeLists

Returns the value of an attribute list whose name matches the one passed in.

sub checkAttributeLists

Parameters

self: This object.
name: The name to look for.

checkShortLongAttributes

Returns the value of an attribute in the object's long or short attributes whose name matches the one passed in.

sub checkShortLongAttributes

Parameters

self: This object.
name: The name to look for.

class

The HeaderDoc class for this object.

sub class

Parameters

self: The object.

Discussion

This is used when blessing a reference to a HeaderDoc object. First, bless the object as a HeaderDoc::HeaderElement, then use its CLASS field to re-bless it as the original subclass.

clearGroup

Clears the group for this object.

sub clearGroup

Parameters

self: This object.

clone

Duplicates this HeaderElement object into another one.

sub clone

Parameters

self: The object to clone.
clone: The victim object.

compositePageUID

Returns a UID suitable for a composite page (when classAsComposite is 0).

sub compositePageUID

Parameters

self: This object.

Discussion

Returns UIDs that begin with //apple_ref/doc/compositePage/ (//apple_ref/doc/compositePage/c/func/myfuncname, for example).

constants

Gets/sets the array of constants associated with an APIOwner, Enum, etc.

sub constants

Parameters

self: The object.
constants: The array of constants to set. (Optional.)

constructor_or_destructor

Returns whether the current function is a constructor or destructor.

sub constructor_or_destructor

Parameters

self: The (generally Function) object.

Return Value

Returns 1 if it is a constructor or destructor, else 0.

dbprint

Prints this object for debugging purposes.

sub dbprint

Parameters

self: This object.
expanded: Pass 1 to expand arrays and other structure, or 0 for normal output.

dbprint_expanded

Prints a variable (e.g. an array) in detail for debugging purposes.

sub dbprint_expanded

Parameters

unknown_var: The variable to print.
leadspace: Leading space characters (or other text) to add to each line of output.

Discussion

Called by dbprint. Do not call directly.

declaration

Gets/sets the vestigial text declaration.

sub declaration

Parameters

self: This object.
declaration: The new declaration to set. (Optional.)

Discussion

This is only relevant if the -b flag is used, and maybe not even then.

declarationInHTML

Prints the declaration with HTML or XML formatting.

sub declarationInHTML

Parameters

self: This object.
declaration: The raw declaration. (Optional.)

Discussion

If you pass in something for declaration, this function computes the declaration based on the parse trees. If you do not pass an argument for declaration, this function returns the cached value from the last call (which could be empty).

declaredIn

Returns the "Declared in" HTML string for a class.

sub declaredIn

Parameters

self: This class object.

DESTROY

Helper called by Perl when this object gets freed.

sub DESTROY

Parameters

self: This object.

discussion

Gets/sets the discussion value.

sub discussion

Parameters

self: This object.
disc: The new value to set. (Optional.)

Discussion

This function returns the discussion, including the nameline discussion, if needed.

discussion_set

Returns true if the discussion is set explicitly with an @discussion tag.

sub discussion_set

Parameters

self: This object.

Discussion

An explicit @discussion tag forces the nameline discussion to be treated as part of the name even if the contents of the discussion tag are empty. This flag supports that.

discussion_sub

Gets the discussion value (private function).

sub discussion_sub

Parameters

self: This object.
bake: Determines whether to bake the results.
discDebug: Set to 1 for debugging, else 0.

Discussion

If a standard discussion is set, this function returns that. If not, this returns the nameline discussion. If code is set, the nameline discussion is wrapped in paragraph tags.

discussionLocked

Stores a backup copy of the abstract and discussion for later use or checks to see if one has been stored.

sub discussionLocked

Parameters

self: The HeaderElement object to modify.
set: If a second parameter is specified, a backup is made.

Return Value

Returns whether the discussion has been backed up or not.

Discussion

Used when parsing @defineblock blocks to restore the discussion and abstract of the block.

documentationBlock

Returns the documentation output for this object (in HTML).

sub documentationBlock

Parameters

self: This object.
composite: Pass 1 if generating a composite page and classAsComposite is 0. Otherwise, pass 0.

doExternalStyle

Returns a string of HTML <link> tags for multiple external stylesheets.

sub doExternalStyle

Parameters

self: This object.
liststring: A list of style sheets separated by spaces.

Discussion

Normally, the list comes from the HeaderDoc config file.

dropParsedParameter

Deletes the last parsed parameter added to this object.

sub dropParsedParameter

Discussion

This is used when rolling things back while handling a badly formed block declaration (one that mixes functions and #defines, for example).

encoding

Returns the character set encoding of the enclosing file.

sub encoding

filename

Gets/sets the filename for a header file.

sub filename

Parameters

self: This object.
filename: The filename to set. (Optional.)

Discussion

This contains the filename as passed in on the command line, with any leading path components stripped off.

firstconstname

Gets/sets the name of the first constant in an enumeration.

sub firstconstname

Parameters

self: This object.
firstconstname: The value to set. (Optional.)

Discussion

If no name could be determiend for an enumeration, this value is used.

fixParseTrees

Adds the main parse tree to the parse tree list if missing.

sub fixParseTrees

Parameters

self: This object.

fixup_inheritDoc

HTML/XML fixup code to insert superclass discussions

sub fixup_inheritDoc

Parameters

self: This object.
html: The block of (discussion) HTML to process.

Discussion

This code inserts the discussion from the superclass wherever <hd_ihd/> appears if possible (i.e. where @inheritDoc (HeaderDoc) or {@inheritDoc} (JavaDoc) appears in the original input material.

For XML, <hd_ihd> and </hd_ihd> tags surround the inherited content.

fixup_values

HTML/XML fixup code to insert values

sub fixup_values

Discussion

This code inserts values wherever <hd_value/> appears (i.e. where @value (HeaderDoc) or {@value} (JavaDoc) appears in the original input material.

fixupParsedParameters

Searches for a parameter in the parsed parameters list. Also takes additional parsed parameters from enclosed structures and adds them to the outer typedef object.

sub fixupParsedParameters

Parameters

self: This object.
name: A name to search for in the original parsed parameters list.

Return Value

Returns 1 if the specified name was found in the original parsed parameters list, else 0.

free

Attempts to detach this object and destroy references to it to release memory.

sub free

Parameters

self: This object.

fullpath

Gets/sets the full path to a header file.

sub fullpath

Parameters

self: This object.
path: The path to set. (Optional.)

Discussion

This contains the path as passed in on the command line, including any leading path components.

functionContents

Gets/sets the function body for a function.

sub functionContents

Parameters

self: This object.
format: The value to set. (Optional.)

generateLinkUID

Generates a special UID for inherited content

sub generateLinkUID

Parameters

self: This object.
composite: Set to 1 if generating for a composite page (if classAsComposite is not 1), else 0.

genRef

Generate a cross-reference request

sub genRef(
    $$$$)

Parameters

keystring

string containing the keywords, e.g. struct or enum

namestring

string containing the type name itself

linktext

link text to generate

optional_expected_type

general genre of expected types

optional_return_only_ref

Pass 1 if you want the bare list of destinations. If the symbol should not be linked, this mode returns an empty string.

Pass 0 (or omit) to get a marked up anchor with link text enclosed. If the word should not be linked, this mode returns the link text.

genRefCore

Generate a cross-reference request

sub genRefCore(
    $$$$$$)

Parameters

keystring

string containing the keywords, e.g. struct or enum

namestring

string containing the type name itself

linktext

link text to generate

expected_type

general genre of expected types

return_only_ref

Pass 1 if you want the bare list of destinations. If the symbol should not be linked, this mode returns an empty string.

Pass 0 (or omit) to get a marked up anchor with link text enclosed. If the word should not be linked, this mode returns the link text.

genRefFromDeclaration

Generate a cross-reference request (from a declaration)

sub genRefFromDeclaration(
    $$$$)

Parameters

keystring

string containing the keywords, e.g. struct or enum

namestring

string containing the type name itself

linktext

link text to generate

optional_expected_type

general genre of expected types

optional_return_only_ref

Pass 1 if you want the bare list of destinations. If the symbol should not be linked, this mode returns an empty string.

Pass 0 (or omit) to get a marked up anchor with link text enclosed. If the word should not be linked, this mode returns the link text.

genRefHTML

Generate a cross-reference request in HTML style

sub genRefHTML(
    $$$)

Parameters

keystring: string containing the keywords, e.g. struct or enum
namestring: string containing the type name itself
linktext: link text to generate
optional_expected_type: general genre of expected types

Discussion

This is used to simplify the code that rips apart the resulting anchor when handling see or seealso tags.

genRefSub

Constructs an API reference from its constituent parts.

sub genRefSub(
    $$$$)

Parameters

self: This HeaderDoc API object.
lang: The programming language.
type: The symbol type.
name: The symbol name.
className: The class containing the symbol (with a trailing slash appended). Pass an empty string if the symbol is not a class member.
paramSignature: The parameter signature for a function or method (prefixed with a leading slash, with parentheses around the actual signature. (Optional.)

getAttributeLists

Returns the attribute lists for this object.

sub getAttributeLists

Parameters

self: This object.
composite: Pass 1 to obtain the list for the composite page, else 0. Used for generating API references for any #define declarations in define blocks.

getAttributes

Returns the attributes for this object, formatted in HTML for output.

sub getAttributes

Parameters

self: This HeaderDoc API object.
long: Pass 0 for short attributes by themselves, 1 for long attributes by themselves, or 2 for both short and long attributes.

getDoxyKind

Returns this object's tag type for use in Doxygen-style tag files.

sub getDoxyKind

Parameters

self: This object.

getMethodType

Returns the method type portion of the API reference for a C++ method.

sub getMethodType

Parameters

self: This HeaderElement object.

getStyle

Returns the CSS style data for the specified name.

sub getStyle

Parameters

self: This object.
name: The name of the style.

group

Gets/sets the group for this object and adds it to the group object.

sub group

Parameters

self: This object.
group: The group to set for this object. (Optional.)

halfbaked_discussion

Returns the discussion (without nameline discussion).

sub halfbaked_discussion

Parameters

self: This object.

Discussion

See name for more info.

headerDocMark

Returns a custom HeaderDoc doc navigator comment for this object.

sub headerDocMark

Parameters

self: This object.
type: The type of the doc navigator comment. Currently valid values are abstract, discussion and declaration.
startend: The word start or end, depending on whether you want a start or end doc navigator comment.

headerDump

Prints a dump of function and #define declarations in this header for debugging purposes.

sub headerDump

Parameters

self: This object.

hideContents

Gets/sets whether this object's contents should be hidden.

sub hideContents

Parameters

self: This object.
hidden: The new value. (Optional.)

Discussion

Function-like macros (with curly braces) are hidden by default. The contents of other macros can be hidden by adding the @hidecontents tag to the comment.

htmlToXML

Converts HTML to XHTML (fast version).

sub htmlToXML

Parameters

self: This object.
htmldata: The data to translate.
droppara: Unused.
debugname: A name to use to identify this block when printing debug info.

Discussion

This version calls into html2xhtml if the content contains tags. Otherwise, it returns the original string immediately.

inDefineBlock

Gets/sets whether this object is a member of a define block.

sub inDefineBlock

Parameters

self: This object.
inblock: The new value.

indexgroup

Sets the index group for a class or header.

sub indexgroup

Discussion

This allows grouping of headers and/or classes in the main TOC generated by gatherHeaderDoc It is unrelated to groupings of functions, etc. within a header.

inheritDoc

Parent discussion for inheritance

sub inheritDoc

Discussion

We don't want to show this, so we can't use an attribute. This is private.

isAPIOwner

Returns whether this is an API owner (class, header, etc.)

sub isAPIOwner

Parameters

self: This object.

Discussion

This is overridden by the APIOwner class.

isBlock

Gets/sets whether this object is a block declaration.

sub isBlock

Parameters

self: This object.
value: The value to set. (Optional.)

Discussion

This should be set to a nonzero value for define blocks and blocks of functions wrapped with #if blocks.

isCallback

Gets/sets whether this is a callback.

sub isCallback

Parameters

self: This object.
istemplate: The value to set. (Optional.)

isFramework

Returns whether this is a framework object.

sub isFramework

Discussion

This is overridden in HeaderDoc::CPPClass.

isFunctionPointer

Gets/sets whether this object is a function pointer.

sub isFunctionPointer

Parameters

self: This object.
ifp: The new value. (Optional.)

isInternal

Gets/sets the ISINTERNAL flag.

sub isInternal

isTemplate

Gets/sets whether this is a template function/class.

sub isTemplate

Parameters

self: This object.
istemplate: The value to set. (Optional.)

keywords

Returns all known keywords for the current language.

sub keywords

Parameters

self: This object.

Return Value

The return value is an array ($case_sensitive, \%keywords).

The first value is either 0 or 1 depending on whether the current language uses case-sensitive token matching or not.

The second value is a reference to a keywords hash for the current language. The specific value is usually 1. Other values are used to indicate that the token should be handled in a non-standard way in certain places.

1. most keywords. 2. attributes and other things where the (...) afterwards must be treated as part of the token. 3. extends keyword. Used for indicating that what follows is stored as the extends info for a class. 4. implements keyword. Used for indicating that what follows is stored as the implements info for a class. 5. throws keywords. Used for indicating that what follows is stored as as an exception that this function throws. 6. __typeof__ keyword where the (...) afterwards must be treated as part of the token; separate from #2 because what follows is a type for code coloring purposes. 7. extern keyword. Use for detecting extern "C". 8. static and my keywords. Used for determining whether global variables are file-scoped. 9. case (shell). Changes parser parenthesis handling. 10. esac (shell). Ends the case statement.

lang

Gets/sets the programming language for this object.

sub lang

Parameters

self: This object.
lang: The new value. (Optional.)

linenum

The line number where a declaration began.

sub linenum

Discussion

We don't want to show this, so we can't use an attribute. This is private.

This uses linenuminblock and blockoffset to get the values. Setting this attribute is no longer supported.

linenuminblock

The line number where a declaration began relative to the block.

sub linenuminblock

Discussion

We don't want to show this, so we can't use an attribute. This is private.

linkageState

Gets/sets the linkage state for this object.

sub linkageState

Parameters

self: This object.
linkagestate: The new value. (Optional.)

linkfix

Retargets HTML links.

sub linkfix

Parameters

self: This object.
inpString: The string of HTML to fix.

listfixup

Converts numbered lists in comments into HTML ordered list tags where possible.

sub listfixup

Parameters

self: This object.
olddiscussion: The input discussion.

Return Value

Returns the new discussion.

masterEnum

Gets/sets whether this array is the "master" enum.

sub masterEnum

Parameters

self: The (generally Enum) object.
newvalue: The value to set. (Optional.)

Discussion

This is legacy cruft that was once used for apple_ref purposes. it is no longer used and should be removed in the future.

mediumrarename

Returns the "medium rare" name.

sub mediumrarename

Parameters

self: This object.

Discussion

Returns the value of the name from the HeaderDoc comment without appending the nameline discussion (ever). See name for more explanation.

name

Gets/sets the name of this function/var/class/*.

sub name

Parameters

self: This object.
name: The value to set. (Optional.)

Discussion

This function returns the name as taken from the HeaderDoc comment. If the nameline contains multiple words and there are additional nonempty discussion lines, the entire name line is treated as the name, and the nameline discussion is appended to the value returned by mediumrarename to obtain the value that this function returns.

An explicit @discussion tag forces the nameline discussion to be treated as part of the name even if the contents of the discussion tag are empty.

This may be a separate value from the rawname and rawname_extended values.

nameline_discussion

Gets/sets the nameline discussion.

sub nameline_discussion

Parameters

self: This object.
disc: The new nameline discusison to set. (Optional.)

Discussion

With old-stype headerdoc comments (e.g. @function), the name line (the first line) contains the name and an optional discussion. If the name line is not the sole discussion, the remainder of the name line is treated as part of the name. Thus, this line gets stored separately.

The content gets massively stripped by this function under the assumption that it may get used as part of a name. You should generally call this version in that context and call raw_nameline_discussion for other cases.

namespace

Sets and returns the namespace of this class.

sub namespace

Parameters

self: The APIOwner object.
namespace: The namespace value to set. (Optional)

new

Creates a new HeaderElement object.

sub new

Parameters

param: A reference to the relevant package object (e.g. HeaderDoc::HeaderElement->new() to allocate a new instance of this class).

noRegisterUID

Gets/sets whether this object should be banned from UID registration.

sub noRegisterUID

Parameters

self: The (generally HeaderElement) object.
value: The value to set. (Optional.)

origClass

Gets/sets the original class info.

sub origClass

Parameters

self: The (generally Function, Method, or Var) object.
origclass: The new value. (Optional.)

Discussion

When the contents of a class are explicitly included in its subclasses using the @superclass tag, the inherited methods and similar get the origClass value set to the owning class so that we don't insert an apple_ref marker for inherited content.

origType

Gets/sets type conversion history.

sub origType

Parameters

self: The HeaderElement object. This is actually applied to the original (pre-conversion) HeaderElement object, but since the underlying keys are copied to the new object, it "just works".
origtype: The new value to set. (Optional.)

Discussion

In blockParseOutside, when you request a specific type (e.g @function), an object of that type is generated. If the resulting declaration should be allowed to match against that type, a conversion occurs, in which a new object of a different type is created with the same contents.

When a conversion occurs, this function records the original requested type for later use.

outputformat

Gets/sets the output format (html, xml).

sub outputformat

Parameters

self: This object.
format: The value to set. (Optional.)

paramMatching

The guts of taggedParamMatching and parsedParamMatching.

sub paramMatching

Parameters

self: This object.
name: The parameter name to search for.
arrayref: A reference to the array of parameters to search.

Return Value

Returns the parameter if it exists, else 0.

parsedParamCompare

Compares the parsed parameters of two methods.

sub parsedParamCompare

Parameters

self: This method object.
compareObj: The method to compare against.

Discussion

When merging methods in from the superclass, methods that are overridden (methods with the same signature) should not be included. This code is intended to perform that check.

parsedParameters

Gets/sets the parsed parameters list for a function, etc.

sub parsedParameters

Parameters

self: This object
pplist: The new parsed parameters list to set. (Optional.)

Discussion

parsedParamMatching

Checks fr a parsed parameter matching a given name.

sub parsedParamMatching

Parameters

self: This object.
name: The parameter name to search for.

Return Value

Returns the parameter if it exists, else 0.

parserState

Gets/sets the parser state.

sub parserState

Parameters

self: This object.
newstate: The new value. (Optional.)

Discussion

Stores a clone of the parser state object for future reference. Rarely used, but important for Objective-C method type identification.

parseTree

Gets/sets the parse tree associated with this object.

sub parseTree

Parameters

self: This object.
parsetree: A reference to the parse tree to set/add. (Optional.)

Discussion

If this is a block declaration, the parse tree is added to its list of parse trees.

parseTreeList

Returns the array of parse trees associated with this object.

sub parseTreeList

Parameters

self: This object.

prepareDiscussionForTemporary

Wipes the discussion and abstract so that defines in a @defineblock can be correctly parsed.

sub prepareDiscussionForTemporary

Parameters

self: The HeaderElement object to modify.

preserve_spaces

Gets/sets whether spaces in the declaration should be preserved.

sub preserve_spaces

Parameters

self: This object.
value: The value to set. (Optional.)

Discussion

This is set high by the presence of an @unformatted tag in the HeaderDoc markup.

printObject

Prints this object for debugging purposes.

sub printObject

Parameters

self: This object.

privateDeclaration

Gets/sets the prvate declaration for a C++ method.

sub privateDeclaration

Parameters

self: This object.
newpridec: The new value to set. (Optional.)

Discussion

The private declaration for a C++ method are the portion of the declaration after the semicolon. These define the private internal variable names that correspond with the public argument names. (Why!?!?!?!)

processComment

Processes a HeaderDoc comment.

sub processComment

Parameters

self

The APIOwner object.

fieldArrayRef

A reference to an array of fields. This should be the result of calling HeaderDoc::Utilities::stringToFields on the HeaderDoc comment.

This is essentially the result of calling split on the @ symbol in the comment, but there is some subtlety involved, so don't do that.

raw_discussion

Returns the discussion without merging in the name line.

sub raw_discussion

Parameters

self: This object.

raw_nameline_discussion

Returns the nameline discussion by itself.

sub raw_nameline_discussion

Parameters

self: This object.

Discussion

Much like nameline_discussion except thiat this variant does not scrape out HeaderDoc markup, HTML tags, etc.

rawname

Returns the "raw" name.

sub rawname

Parameters

self: This object.

Discussion

Returns the value of the name from the HeaderDoc comment without further processing.

If no "raw" name was set, returns the main name (from mediumrarename.

rawname_extended

Returns the "raw" name.

sub rawname_extended

Parameters

self: This object.

Discussion

An explicit @discussion tag forces the nameline discussion to be treated as part of the name even if the contents of the discussion tag are empty.

This may be a separate value from the main name returned by name and mediumrarename.

If no "raw" name was set, returns the main name (equivalent to name.

requestedUID

Sets an override API uid for the rare cases where they would conflict by nature.

sub requestedUID

Discussion

This is triggered by the presence of an @apiuid tag in the HeaderDoc comment block (usually for a header file).

result

Gets/sets the result (return values) text for functions, Objective-C methods, function-like macros, structures containing callbacks, type definitions containing callbacks, and Objective-C properties. etc.

sub result

Parameters

self: The Function object.
resultstring: The string to set. (Optional.)

Discussion

This comes from the @result, @return, or @returns tag in the HeaderDoc comment.

returntype

Gets/sets the return type for this object.

sub returntype

Parameters

self: This object.
returntype: The new value. (Optional.)

see

Add see/seealso (JavaDoc compatibility enhancement)

sub see

seeDupCheck

Gets/sets the SEEALSODUPCHECK value.

sub seeDupCheck

Parameters

self: This object.
name: The value to set. (Optional.)

Discussion

This is used when doing cross-linking between multiple objects (in blockParseOutside) to ensure that duplicate entries are not inserted.

setAPIOBackReferences

Clears references to higher nodes in the object graph.

sub setAPIOBackReferences

Parameters

self: The APIOwner object. (Unused)
listref: A list of objects to modify.
freechildren: Pass 1 to call the free method on this object's children, else 0.

setStyle

Sets the CSS for a particular style name.

sub setStyle

Parameters

self: This object.
name: The name of the style.
style: The CSS style data.

splitmerge

Merges newlines and carriage returns with preceding text, but only if nonsequential.

sub splitmerge

Parameters

arrayref: A reference to the input array.

Return Value

Returns the new array.

Discussion

For proper interpreting of implicit lists (without ul or ol tags), it is necessary to split the input into lines of text, keeping the first newline/carriage return attached to the previous line, but not later newlines or carriage returns.

strcasecmp

Compares two strings in a case-insensitive fashion.

sub strcasecmp(
    $$)

Parameters

a: The first string.
b: The second string.

strdate

A function for converting numeric dates into strings.

sub strdate(
    $$$$)

Parameters

month: Month in the range 0-11 (not 1-12).
day: Day of the month.
year: Year (four-digit).

Local Variables

format: A time format suitable for strftime. Extracted from the HeaderDoc configuration file. Also contains a compatibility hack for compatibility with the old HeaderDoc date format codes.

styleSheet

Returns the complete CSS stylesheet for HeaderDoc content.

sub styleSheet

Parameters

self: This object.
TOC: Set to 1 if you are generating styles for the left-side TOC frame, else 0.

sublang

Gets/sets the programming language dialect for this object.

sub sublang

Parameters

self: This object.
sublang: The new value. (Optional.)

Discussion

The dialect, sublang, represents a more specific language than the main language in some cases. For example, with C-based languages, the language is C, but the sublang can be C (standard C, translated to a lowercase c in the actual API reference), occ (Objective-C), cpp (C++), etc.

suppressChildren

Gets/sets whether this object's children should be suppressed.

sub suppressChildren

Parameters

self: The (generally HeaderElement) object.
value: The value to set. (Optional.)

Discussion

An object's children are generally suppressed for the outer typedef linked to a separate struct or enum declaration, e.g. when the @typedef comment is followed by an enum declaration, followed by the actual typedef.

When an object's children (parsed/tagged parameters, fields, etc.) are suppressed, no UIDs are generated for the objects, and the tagged/parsed parameter comparison does not occur. Output from any explicitly tagged parameters is still emitted, however. The reason for this is that the parsed parameters aren't really associated with the typedef, so you'd get lots of warnings.

taggedParameters

Gets/sets the tagged parameters list for a function, etc.

sub taggedParameters

Parameters

self: This object
tplist: The new tagged parameters list to set. (Optional.)

Discussion

The tagged parameters list is an array of MinorAPIElement objects that represent the parameters as tagged in the HeaderDoc comment block.

taggedParamFind

Finds a tagged parameter by name.

sub taggedParamFind

Discussion

To improve Doxygen tag compatibility, HeaderDoc concatenates multiple @param tags for the same parameter name. This is part of that support.

taggedParamMatching

Checks fr a tagged parameter matching a given name.

sub taggedParamMatching

Parameters

self: This object.
name: The parameter name to search for.

Return Value

Returns the parameter if it exists, else 0.

taggedParsedCompare

Compares tagged parameters to parsed parameters (for validation)

sub taggedParsedCompare

Parameters

self: This object.

tagNameRegexpAndSuperclassFieldNameForType

Returns HeaderDoc tag names and English names for a given HeaderDoc object.

sub tagNameRegexpAndSuperclassFieldNameForType

Parameters

self: This object.

Discussion

Returns an array with three members: the English name, a regular expression to match the tag names that make sense for this object, and (if applicable) the superclass field name.

For example, an instance of the HeaderDoc::Function class returns an english name of function or method, and returns a regular expression that matches either the function or method HeaderDoc tags. Because it cannot have a superclass, it doesn't need to return anything for the third field.

textToXML

Encodes text into HTML/XML entities.

sub textToXML

Parameters

self: This object.
textdata: The text to convert.

throws

Gets/sets the list of exceptions thrown by this class/function.

sub throws

Parameters

self: The current object.
throws: The new value. (Optional.)

typedefContents

Gets/sets the contents of a simple typedef.

sub typedefContents

Parameters

self: The (generally Typedef) object.
contents: The value to set. (Optional.)

Discussion

This is populated by the simpleTDcontents field in the parser state object.

unlockDiscussion

Restores a backup copy of the abstract and discussion stored by discussionLocked.

sub unlockDiscussion

Parameters

self: The HeaderElement object to modify.

Discussion

Used when parsing @defineblock blocks to restore the discussion and abstract of the block.

unregister

Unregisters this object.

sub unregister

Parameters

self: This object.

Discussion

This function unregisters the descendents of this object from the UID conflict detection code and marks this object in such a way that its UID will never be reregistered.

You should generally not call this unless you are about to dispose of the object.

updated

Gets/sets the last updated date for this object.

sub updated

Parameters

self: This object.
updated: The new value. (Optional.)

use_stdout

Gets/sets the USESTDOUT flag (0/1).

sub use_stdout

Parameters

self: This object.
format: The value to set. (Optional.)

Discussion

If 0, the output is sent to files as usual. If 1, the XML output is sent to stdout.

value

Value for constants, variables, etc.

sub value

Discussion

This is not typically shown in the HTML output, so this can't be stored in a normal attribute.

variables

Gets/sets the array of local variables associated with a function, etc.

sub variables

Parameters

self: The (generally Function) object.
variables: The array of variables to set. (Optional.)

wipeUIDCache

Wipes any cached API and/or link UIDs for this object.

sub wipeUIDCache

Parameters

self: This object.

XMLabstract

Returns the abstract for XML use.

sub XMLabstract

Parameters

self: This object.

Discussion

The value is set with abstract.

XMLdiscussion

Returns the discussion formatted for XML.

sub XMLdiscussion

Parameters

self: This object.
deprecated_discussion: The value to set. (Optional, do not use.)

Discussion

Do not set discussion with this function. Use the discussion function instead.

XMLdocumentationBlock

Returns the documentation output for this object (in XML).

sub XMLdocumentationBlock

Parameters

self: This object.

XMLthrows

Returns the list of exceptions thrown by this class/function.

sub XMLthrows

Parameters

self: The current object.

Discussion

The value is set with throws.

Member Data

ABSTRACT: The contents of the associated @abstract tag.
ABSTRACTLOCKED: Temporary storage for the ABSTRACT field, used when fields are locked during define block parsing. For more information, see the documentation for the discussionLocked and unlockDiscussion functions.
ACCESSCONTROL: The access control state for this API element (e.g. public, private...)
APIOWNER: The APIOwner object whose declaration includes this one. This owning object may be a class, header, protocol, category, etc.
APIREFSETUPDONE: Set to 1 when the apirefSetup call finishes. This avoids doing unnecessary work (and makes the UID collision protection easier).
APIUID: A cache of the raw UID for this object. Set by apiuid. This is not actually used because it is often wrong.
APPLEREFISDOC: Holds 1 if this object should emit a doc-style API reference, else 0.
ATTRIBUTELISTS: The list-style attributes associated with this API element. See attributelist, getAttributeLists, and checkAttributeLists.
AUTORELATE: Used to store a list of automatically-generated cross-references for blocks containing mixed types. For more information, see the documentation for the autoRelate function.
AVAILABILITY: The availability information for this element (from @availability or from availability macros.
BLOCKOFFSET: The offset of the start of the block of lines in which this declaration appears. (Added to RAWLINENUM to get the actual line number.)
CASESENSITIVE: A cache of the value for case sensitivity from the last time the keywords method was called.
CLASS: The HeaderDoc object class for this object (e.g. HeaderDoc::Method). Used to bless the object properly from a hash reference.
CONSTANTS: An array of constants in this enumeration or API owner object. Each item in this array is a MinorAPIElement object.
DECLARATION: The (vestigial) text declaration for this element.
DECLARATIONINHTML: A cache of the HTML declaration for this element.
DISCUSSION: The contents of the @discussion tag (or untagged content elsewhere in the comment).
DISCUSSION_SET: Set to 1 when an actual discussion has been seen. This is used to determine whether additional words in the name line should be treated as discussion or part of the name. See nameline_discussion for more info.
DISCUSSION_SETLOCKED: Temporary storage for the DISCUSSION_SET field, used when fields are locked during define block parsing. For more information, see the documentation for the discussionLocked and unlockDiscussion functions.
DISCUSSIONLOCKED: Temporary storage for the DISCUSSION field, used when fields are locked during define block parsing. For more information, see the documentation for the discussionLocked and unlockDiscussion functions.
FIELDHEADING: A cache of the last field heading displayed. Unused.
FIELDS: An array of fields in this struct, union, or typedef.
FILENAME: The filename containing this declaration (with leading path parts removed).
FIRSTCONSTNAME: The first constant name within an enumeration. Used as the name of an anonymous enumeration if no name is specified in the comment.
FULLPATH: The filename containing this declaration (with leading parts left intact).
FUNCORMETHOD: A cache of the last func_or_method value returned by apirefSetup. Unused.
FUNCTIONCONTENTS: The contents within the outer braces of a function.
GROUP: The name of the (documentation) group that this object is in.
HASPROCESSEDCOMMENT: Set to 1 after the processComment function has executed. This prevents doing that twice (which would cause a number of problems).
HeaderDoc::HeaderElement::VERSION: The revision control revision number for this module.
HIDECONTENTS: Set to 1 if the @hidecontents tag is found in a macro's HeaderDoc comment. See hideContents.
HIDEDOC: Set by the block parser to indicate that this object should not emit any documentation. This is set on #define objects within a #define block if the HIDESINGLETONS flag is set on the enclosing block.
HIDESINGLETONS: This flag is set (to 1) if the @hidesingletons tag is found inside an @defineblock (or @definedblock) comment.
INCLUDED_DEFINES: An array of #define objects nested in an @defineblock (or @definedblock).
INDEFINEBLOCK: Set on individual #define objects within an @defineblock (or @definedblock).
INDEXGROUP: The group in which this object and its descendants should appear inside the master TOC as generated by gatherHeaderDoc.pl.
INHERITDOC: The discussion for the superclass. Inserted if requested. See fixup_inheritDoc.
INSERTED: Set to 42 once this object has been added to its enclosing API owner.
ISBLOCK: Set to 1 for #define blocks, 2 for #ifdef blocks around multiple variants of a function.
ISCALLBACK: Set to 1 for a typedef of a callback.
ISDEFINE: Set for #define members in a non-#define block to prevent lovely problems.
ISFUNCPTR: Set to 1 for a variable or type definition if the @result tag is included.
ISINTERNAL: Set to 1 for internal variables/functions that should only be documented if a special flag is set.
ISTEMPLATE: Set for functions that have template parameters.
KEEPCONSTANTS: A cached array of constants generated by apirefSetup.
KEEPFIELDS: A cached array of fields generated by apirefSetup.
KEEPPARAMS: A cached array of parameters generated by apirefSetup.
KEEPVARIABLES: A cached array of variables generated by apirefSetup.
KEYWORDHASH: A cache of the keyword hash from the last time the keywords method was called.
LANG: The programming language for this declaration.
LINENUM: The line number in which this declaration begins relative to the start of the header. (This is the sum ofBLOCKOFFSET and RAWLINENUM.)
LINKAGESTATE: The linkage state. Unused.
LINKUID: A cache of the "link UID". See generateLinkUID.
LONGATTRIBUTES: An array of "long" attributes (those containing multiple paragraphs as opposed to just a line or so).
MAINOBJECT: The main object (block object) in a block declaration.
MASTERENUM: The main enum object that owns the enclosing constants. Originally used for apple_ref emission purposes. Unused.
NAME: The name of the API symbol that this object represents. Usually accessed with name.
NAMELINE_DISCUSSION: The portion of the discussion that appears on the same line as the name in an old-style HeaderDoc comment. See nameline_discussion for more information.
NAMEREFS: An array of names for this object that appear within the HeaderDoc::namerefs array. Used when destroying this object to allow those references to be destroyed.
NAMESPACE: Contains a text string representing the namespace for this class. See namespace.
NOREGISTERUID: Set to 1 when an object's UID has been unregistered to prevent it from being registered again. See noRegisterUID.
ORIGCLASS: The name of the class that a method, variable, etc. was inherited from. See origClass.
ORIGTYPE: The type of the original object (generated based on the HeaderDoc comment) from which this object (of a different type) was later cloned. For more information, see the documentation for the origType function.
OUTPUTFORMAT: The current output format ("html" or "hdxml").
PARSEDPARAMETERS: For methods, an array of parsed parameters for a method. For a structure, union, or type definition, an array of parsed fields. For an enumaration, an array of parsed constants.
PARSERSTATE: The parser state object associated with this API object.
PARSETREE: The parse tree object containing the declaration for this API object.
PARSETREECLEANUP: An array of parse tree objects that reference this API object. Used when destroying this object to allow those references to be destroyed.
PARSETREELIST: An array of parse trees containing the declarations for API objects within this block-style API object. Only relevant if isBlock returns 1.
PPFIXUPDONE: Set to 1 to indicate that fixupParsedParameters has already been called on this object.
PRESERVESPACES: Set to 1 to indicate that the user wants to preserve whitespace within this declaration. See preserve_spaces.
PRIVATEDECLARATION: The private declaration portion of a C++ method (after the colon).
RAWLINENUM: The line number in which this declaration begins relative to the start of the block of lines. (Added to BLOCKOFFSET to get the actual line number.)
RAWNAME: See rawname.
REQUESTEDUID: A UID explicitly provided with the @apiuid tag. See requestedUID.
RETURNTYPE: The return type for a function (parsed from the code).
SEEALSODUPCHECK: Used to prevent duplicates in auto-generated cross-linking. See seeDupCheck for details.
SINGLEATTRIBUTES: An array of "short" attributes (those containing just a word or a line as opposed to multiple paragraphs).
SUBLANG: The programming language variant for this object (e.g. cpp for C++).
SUPPRESSCHILDREN: Indicates that UIDs for child elements (e.g. fields) should be suppressed in the HTML output. See suppressChildren for more information.
TAGGEDPARAMETERS: An array of explicitly tagged (@param) parameters in a function/method.
THROWS: The content of the @throws tag in the comment (with HTML formatting added). See also XMLTHROWS below.
TPCDONE: Set to 1 after taggedParsedCompare is called so that this isn't done repeatedly for the same function, union, struct, or typedef.
TYPEDEFCONTENTS: The contents of a typedef declaration.
UPDATED: The last updated date. See updated.
USESTDOUT: Set to 1 if the -P (pipe) flag is passed to HeaderDoc, else 0.
VALUE: The value of a constant/variable. See value.
VARIABLES: An array of variables enclosed in a normal (usually function) object. These are MinorAPIElement objects.
VARS: An array of variables enclosed in an API owner object. These are Var objects.
XMLTHROWS: A copy of the value in THROWS with XML formatting.

ABSTRACT

The contents of the associated @abstract tag.

$self->{ABSTRACT}

ABSTRACTLOCKED

Temporary storage for the ABSTRACT field, used when fields are locked during define block parsing. For more information, see the documentation for the discussionLocked and unlockDiscussion functions.

$self->{ABSTRACTLOCKED}

ACCESSCONTROL

The access control state for this API element (e.g. public, private...)

$self->{ACCESSCONTROL}

APIOWNER

The APIOwner object whose declaration includes this one. This owning object may be a class, header, protocol, category, etc.

$self->{APIOWNER}

APIREFSETUPDONE

Set to 1 when the apirefSetup call finishes. This avoids doing unnecessary work (and makes the UID collision protection easier).

$self->{APIREFSETUPDONE}

APIUID

A cache of the raw UID for this object. Set by apiuid. This is not actually used because it is often wrong.

$self->{APIUID}

APPLEREFISDOC

Holds 1 if this object should emit a doc-style API reference, else 0.

$self->{APPLEREFISDOC}

ATTRIBUTELISTS

The list-style attributes associated with this API element. See attributelist, getAttributeLists, and checkAttributeLists.

$self->{ATTRIBUTELISTS}

AUTORELATE

Used to store a list of automatically-generated cross-references for blocks containing mixed types. For more information, see the documentation for the autoRelate function.

$self->{AUTORELATE}

AVAILABILITY

The availability information for this element (from @availability or from availability macros.

$self->{AVAILABILITY}

BLOCKOFFSET

The offset of the start of the block of lines in which this declaration appears. (Added to RAWLINENUM to get the actual line number.)

$self->{BLOCKOFFSET}

CASESENSITIVE

A cache of the value for case sensitivity from the last time the keywords method was called.

$self->{CASESENSITIVE}

CLASS

The HeaderDoc object class for this object (e.g. HeaderDoc::Method). Used to bless the object properly from a hash reference.

$self->{CLASS}

CONSTANTS

An array of constants in this enumeration or API owner object. Each item in this array is a MinorAPIElement object.

$self->{CONSTANTS}

DECLARATION

The (vestigial) text declaration for this element.

$self->{DECLARATION}

DECLARATIONINHTML

A cache of the HTML declaration for this element.

$self->{DECLARATIONINHTML}

DISCUSSION

The contents of the @discussion tag (or untagged content elsewhere in the comment).

$self->{DISCUSSION}

DISCUSSION_SET

Set to 1 when an actual discussion has been seen. This is used to determine whether additional words in the name line should be treated as discussion or part of the name. See nameline_discussion for more info.

$self->{DISCUSSION_SET}

DISCUSSION_SETLOCKED

Temporary storage for the DISCUSSION_SET field, used when fields are locked during define block parsing. For more information, see the documentation for the discussionLocked and unlockDiscussion functions.

$self->{DISCUSSION_SETLOCKED}

DISCUSSIONLOCKED

Temporary storage for the DISCUSSION field, used when fields are locked during define block parsing. For more information, see the documentation for the discussionLocked and unlockDiscussion functions.

$self->{DISCUSSIONLOCKED}

FIELDHEADING

A cache of the last field heading displayed. Unused.

$self->{FIELDHEADING}

FIELDS

An array of fields in this struct, union, or typedef.

$self->{FIELDS}

FILENAME

The filename containing this declaration (with leading path parts removed).

$self->{FILENAME}

FIRSTCONSTNAME

The first constant name within an enumeration. Used as the name of an anonymous enumeration if no name is specified in the comment.

$self->{FIRSTCONSTNAME}

FULLPATH

The filename containing this declaration (with leading parts left intact).

$self->{FULLPATH}

FUNCORMETHOD

A cache of the last func_or_method value returned by apirefSetup. Unused.

$self->{FUNCORMETHOD}

FUNCTIONCONTENTS

The contents within the outer braces of a function.

$self->{FUNCTIONCONTENTS}

GROUP

The name of the (documentation) group that this object is in.

$self->{GROUP}

HASPROCESSEDCOMMENT

Set to 1 after the processComment function has executed. This prevents doing that twice (which would cause a number of problems).

$self->{HASPROCESSEDCOMMENT}

HeaderDoc::HeaderElement::VERSION

The revision control revision number for this module.

$HeaderDoc::HeaderElement::VERSION = '$Revision: 1341011599 $';

Discussion

In the git repository, contains the number of seconds since January 1, 1970.

HIDECONTENTS

Set to 1 if the @hidecontents tag is found in a macro's HeaderDoc comment. See hideContents.

$self->{HIDECONTENTS}

HIDEDOC

Set by the block parser to indicate that this object should not emit any documentation. This is set on #define objects within a #define block if the HIDESINGLETONS flag is set on the enclosing block.

$self->{HIDEDOC}

HIDESINGLETONS

This flag is set (to 1) if the @hidesingletons tag is found inside an @defineblock (or @definedblock) comment.

$self->{HIDESINGLETONS}

INCLUDED_DEFINES

An array of #define objects nested in an @defineblock (or @definedblock).

$self->{INCLUDED_DEFINES}

INDEFINEBLOCK

Set on individual #define objects within an @defineblock (or @definedblock).

$self->{INDEFINEBLOCK}

INDEXGROUP

The group in which this object and its descendants should appear inside the master TOC as generated by gatherHeaderDoc.pl.

$self->{INDEXGROUP}

INHERITDOC

The discussion for the superclass. Inserted if requested. See fixup_inheritDoc.

$self->{INHERITDOC}

INSERTED

Set to 42 once this object has been added to its enclosing API owner.

$self->{INSERTED}

ISBLOCK

Set to 1 for #define blocks, 2 for #ifdef blocks around multiple variants of a function.

$self->{ISBLOCK}

ISCALLBACK

Set to 1 for a typedef of a callback.

$self->{ISCALLBACK}

ISDEFINE

Set for #define members in a non-#define block to prevent lovely problems.

$self->{ISDEFINE}

ISFUNCPTR

Set to 1 for a variable or type definition if the @result tag is included.

$self->{ISFUNCPTR}

ISINTERNAL

Set to 1 for internal variables/functions that should only be documented if a special flag is set.

$self->{ISINTERNAL}

ISTEMPLATE

Set for functions that have template parameters.

$self->{ISTEMPLATE}

KEEPCONSTANTS

A cached array of constants generated by apirefSetup.

$self->{KEEPCONSTANTS}

KEEPFIELDS

A cached array of fields generated by apirefSetup.

$self->{KEEPFIELDS}

KEEPPARAMS

A cached array of parameters generated by apirefSetup.

$self->{KEEPPARAMS}

KEEPVARIABLES

A cached array of variables generated by apirefSetup.

$self->{KEEPVARIABLES}

KEYWORDHASH

A cache of the keyword hash from the last time the keywords method was called.

$self->{KEYWORDHASH}

LANG

The programming language for this declaration.

$self->{LANG}

LINENUM

The line number in which this declaration begins relative to the start of the header. (This is the sum ofBLOCKOFFSET and RAWLINENUM.)

$self->{LINENUM}

LINKAGESTATE

The linkage state. Unused.

$self->{LINKAGESTATE}

LINKUID

A cache of the "link UID". See generateLinkUID.

$self->{LINKUID}

LONGATTRIBUTES

An array of "long" attributes (those containing multiple paragraphs as opposed to just a line or so).

$self->{LONGATTRIBUTES}

MAINOBJECT

The main object (block object) in a block declaration.

$self->{MAINOBJECT}

MASTERENUM

The main enum object that owns the enclosing constants. Originally used for apple_ref emission purposes. Unused.

$self->{MASTERENUM}

NAME

The name of the API symbol that this object represents. Usually accessed with name.

$self->{NAME}

NAMELINE_DISCUSSION

The portion of the discussion that appears on the same line as the name in an old-style HeaderDoc comment. See nameline_discussion for more information.

$self->{NAMELINE_DISCUSSION}

NAMEREFS

An array of names for this object that appear within the HeaderDoc::namerefs array. Used when destroying this object to allow those references to be destroyed.

$self->{NAMEREFS}

NAMESPACE

Contains a text string representing the namespace for this class. See namespace.

$self->{NAMESPACE}

NOREGISTERUID

Set to 1 when an object's UID has been unregistered to prevent it from being registered again. See noRegisterUID.

$self->{NOREGISTERUID}

ORIGCLASS

The name of the class that a method, variable, etc. was inherited from. See origClass.

$self->{ORIGCLASS}

ORIGTYPE

The type of the original object (generated based on the HeaderDoc comment) from which this object (of a different type) was later cloned. For more information, see the documentation for the origType function.

$self->{ORIGTYPE}

OUTPUTFORMAT

The current output format ("html" or "hdxml").

$self->{OUTPUTFORMAT}

PARSEDPARAMETERS

For methods, an array of parsed parameters for a method. For a structure, union, or type definition, an array of parsed fields. For an enumaration, an array of parsed constants.