headerDoc2HTML.pl

Introduction

The main HeaderDoc tool, headerDoc2HTML.pl (headerdoc2html when installed), translates a header file (or source code file) into HTML (or XML).

This document provides API-level documentation on the tool's internals. For user documentation, see HeaderDoc User Guide.

Functions

depthfirst

Depth-first tree walk used in determining dependency order.

depthfirst_rec

Recursive portion of depth-first tree walk used in determining dependency order.

fix_dependency_order

Reorders a list of C headers in dependency order.

generate_depth_levels

Lays out dependencies in a tree structure.

getDoxyTagFiles

Search helper for Doxygen-style tag files.

getHeaders

Search helper for header files.

in_exclude_list

Checks the exclude list for filenames.

mergeClass

Merges superclass bits into subclass upon request.

mergeDoxyTags

Merge doxygen tag files and delete the partial files.

mkdir_recursive

Creates directories recursively as needed.

newtest

Creates a new test for the test framework.

prefilterCommentCheck

Checks for comment characters in a line and adjusts an inComment variable accordingly, returning the new value.

printCPPHashes

Prints the CPP hashes for debugging purposes.

printVersionInfo

Collects version info from HeaderDoc modules and prints.

processIncludes

Grabs any #include directives.

runResolveLinksTests

Runs the resolveLinks test suite.

runtestlist

Runs multiple tests using the test framework.

runtests

Runs a test using the test framework.

SDump

Test code for dumping notes in dependency tree.

set_node_depths

Sets node depth information in the tree structure as part of the depth-first tree walk code.

setTOCFormat

Sets the TOC format value based on its name.

strip

Strips out HeaderDoc comments from a header.

depthfirst

Depth-first tree walk used in determining dependency order.

sub depthfirst 

depthfirst_rec

Recursive portion of depth-first tree walk used in determining dependency order.

sub depthfirst_rec 

fix_dependency_order

Reorders a list of C headers in dependency order.

sub fix_dependency_order 

Return Value

Returns the result of a depth-first walk of the dependency graph in the form of a dependency-ordered array.

Discussion

The dependency calculation is fairly straightforward. For each header, HeaderDoc reads the list of #include and #import directives. Then, for each input file:

• HeaderDoc looks to see if a dependency object with that filename exists. A preexisting dependency object can occur for two reasons: because another header has declared a dependency on it previously or because another header with the same name has already been scanned.

• If the dependency exists and the EXISTS flag is set on that object, HeaderDoc knows that it has already processed a header with the same name, and HeaderDoc emits a warning, then creates a new dependency object.

• If the dependency object exists and the EXISTS flag is not set. HeaderDoc sets the EXISTS flag on the existing dependency object.

• If the dependency object does not exist, it creates a new node and sets the EXISTS flag.

• HeaderDoc creates dependencies for each header that it includes, nested within the dependency object for this input file.

After creating these child dependencies for every header, the result is a graph of dependencies, with cycles.

Finally, the code performs a depth-first walk of the graph (with cycle detection). Because each object is guaranteed to be lower in the graph for at least one path through the graph than any file on which it depends (ignoring circular dependencies), this is sufficient to ensure that any file is processed prior to any file that it includes.

Local Variables

generate_depth_levels

Lays out dependencies in a tree structure.

sub generate_depth_levels 

getDoxyTagFiles

Search helper for Doxygen-style tag files.

sub getDoxyTagFiles 

Discussion

During processing, each source file results in a corresponding Doxygen-style tag file (if the -x flag is specified). This search helper is used in tracking those files down for merging at the end of processing.

getHeaders

Search helper for header files.

sub getHeaders 

Discussion

This is used for comparing names against the list of valid file extensions to see if they should be processed by HeaderDoc.

in_exclude_list

Checks the exclude list for filenames.

sub in_exclude_list(
    $) 

Discussion

When you specify an exclude list (the -e flag), HeaderDoc reads that file for a list of expressions to match. Every time HeaderDoc opens a header file, source file, or other file to process, it checks it against that list by calling this function.

mergeClass

Merges superclass bits into subclass upon request.

sub mergeClass 

Discussion

The mergeClass function is used for merging bits of a superclass into subclasses when the @superclass tag is specified.

It is also always used for C psuedoclass classes because any pseudo-superclass relationship isn't really a superclass.

mergeDoxyTags

Merge doxygen tag files and delete the partial files.

sub mergeDoxyTags 

mkdir_recursive

Creates directories recursively as needed.

sub mkdir_recursive 

Discussion

This is the Perl equivalent of "mkdir -p" on the command line.

newtest

Creates a new test for the test framework.

sub newtest 

Discussion

See HeaderDoc User Guide for info about creating tests.

prefilterCommentCheck

Checks for comment characters in a line and adjusts an inComment variable accordingly, returning the new value.

sub prefilterCommentCheck 

Parameters

Return Value

Returns the new value for inComment.

printCPPHashes

Prints the CPP hashes for debugging purposes.

sub printCPPHashes 

printVersionInfo

Collects version info from HeaderDoc modules and prints.

sub printVersionInfo 

processIncludes

Grabs any #include directives.

sub processIncludes(
    $$$) 

runResolveLinksTests

Runs the resolveLinks test suite.

sub runResolveLinksTests 

runtestlist

Runs multiple tests using the test framework.

sub runtestlist 

Discussion

See HeaderDoc User Guide for info about running tests.

runtests

Runs a test using the test framework.

sub runtests 

Discussion

See HeaderDoc User Guide for info about running tests.

SDump

Test code for dumping notes in dependency tree.

sub SDump 

set_node_depths

Sets node depth information in the tree structure as part of the depth-first tree walk code.

sub set_node_depths 

setTOCFormat

Sets the TOC format value based on its name.

sub setTOCFormat 

Discussion

Returns values via $HeaderDoc::newTOC. Possible values are:

0. Old TOC style (ugly).

1. Apple old-style TOC.

2. Apple interim TOC.

3. Apple new-style TOC.

4. Unused.

5. Public new-style TOC.

strip

Strips out HeaderDoc comments from a header.

sub strip 

Globals

debugging

Storage for the -d flag.

doxytag_output

Storage for the -x flag.

doxyTagFiles

Temp storage for list of temp files.

function_list_output

Storage for the -f flag.

functionGroup

The name of the current function group.

HeaderDoc::AccessControlState

The current access control state used and modified by the parser.

HeaderDoc::add_link_requests

Disables link requests in declarations (-l flag).

HeaderDoc::align_columns

Storage for the -a flag.

HeaderDoc::allow_multi

Determines whether to treat commented #if/#ifdef blocks as blocks of related functions.

HeaderDoc::appleRefUsed

A hash of all API reference markers for minir API elements emitted so far.

HeaderDoc::auto_availability

Storage for the --auto-availability flag.

HeaderDoc::availability_defs

A hash table mapping availability macros to the text that describes them.

HeaderDoc::availability_has_args

A hash table mapping availability macros to whether or not the macro declaration takes a parenthesized argument list.

HeaderDoc::c_compiler

The default C compiler.

HeaderDoc::ClassAsComposite

Storage for the -C flag.

HeaderDoc::cppArgHashList

A list of C preprocessor argument hashes for the current header.

HeaderDoc::cppHashList

A list of C preprocessor token hashes for the current header.

HeaderDoc::CurLine

The current line number being parsed.

HeaderDoc::currentClass

Used to set the owning class when processing embedded API symbols.

HeaderDoc::custom_tags

A reference to a hash of non-standard tags to allow.

HeaderDoc::datefmt

The date format used for date stamps.

HeaderDoc::debugAllocations

Turns on debug output when objects are allocated and released.

HeaderDoc::debugFile

Set to the name of a file to tell HeaderDoc to enable debugging when processing that file.

HeaderDoc::defaultHeaderComment

The default comment in the right side if a header or class lacks a discussion.

HeaderDoc::document_internal

Enable internal documentation.

HeaderDoc::dumb_as_dirt

Deprecated.

HeaderDoc::enable_cpp

Storage for the -p or --enable-cpp flag.

HeaderDoc::enable_macro_filter

Set if any -D or -U flags are passed on the command line.

HeaderDoc::enable_reverse_match

Determines whether the macro filter code should treat the != token as a == token due to consistent eccentricities in what is being parsed.

HeaderDoc::enableParanoidWarnings

Storage for the -Q (disquiet) flag.

HeaderDoc::exclude_patterns

The list of filename patterns to exclude when producing documentation.

HeaderDoc::exitstatus

The exit status. Changed to nonzero whenever an error occurs.

HeaderDoc::explicit_toc_format

Storage for the tocformat value from the config file.

HeaderDoc::externalStyleSheets

Storage for the externalStyleSheets value from the config file.

HeaderDoc::externalTOCStyleSheets

Storage for the externalTOCStyleSheets value from the config file.

HeaderDoc::ExtraAppleWarnings

Flags certain XML tags as illegal due to Apple-internal constraints.

HeaderDoc::fileDebug

Set to 1 if you need to enable lots of debugging for a single file.

HeaderDoc::filter_macro_definition_state

A hash of macro definition states passed in on the command line that are interpreted by the macro filter engine.

HeaderDoc::filter_macro_definition_value

A hash of macro values passed in on the command line that are interpreted by the macro filter engine.

HeaderDoc::flagDashC

Storage for the -C flag. Set to -1 if flag is set.

HeaderDoc::flagDashF

Storage for the -F flag (legacy frames output mode).

HeaderDoc::force_parameter_tagging

Enables strict parameter taggint warnings (-t flag).

HeaderDoc::FreezeThaw_available

Indicates whether the FreezeThaw Perl module is available.

HeaderDoc::globalGroup

The name of the current group.

HeaderDoc::groupright

Sorts content in the right side (content) pane by group.

HeaderDoc::HeaderFileCPPArgHashHash

Hash of argument lists for C preprocessor macros.

HeaderDoc::HeaderFileCPPHashHash

Hash of C preprocessor token hashes for files processed to date.

HeaderDoc::headerObject

Global header object for the header currently being parsed.

HeaderDoc::hidetokens

Indicates that all token objects should be marked hidden.

HeaderDoc::idl_language

The API reference language for IDL file content.

HeaderDoc::ignore_apiowner_names

Storage for the -n and -N flags.

HeaderDoc::ignore_apiuid_errors

Set to true when HeaderDoc should suppress warnings about API reference conficts, object name changes, and so on.

HeaderDoc::ignorePrefixes

Deprecated.

HeaderDoc::IncludeSuper

Storage for the -S flag.

HeaderDoc::insert_header

Storage for the -H flag.

HeaderDoc::interpret_case

Determines whether the macro filter code attempts to handle switch and case statements.

HeaderDoc::introductionName

Storage for the introductionName configuration file field.

HeaderDoc::lang

Global variable where the language family info for the header currently being parsed is stored.

HeaderDoc::man_section

Storage for the -M flag.

HeaderDoc::maxDecLen

Maximum line length for wrapping declarations.

HeaderDoc::modulesPath

The location from which the HeaderDoc modules were loaded.

HeaderDoc::nameFromAPIRefReturnsOnlyName

Storage for the bareNamesFromAPIRefs flag

HeaderDoc::namerefs

Used for quickly looking up names of fields in data types by the data type name and field name.

HeaderDoc::newTOC

New TOC style variable.

HeaderDoc::outerNamesOnly

Enables/disables "outer name" type handling (-O flag).

HeaderDoc::parse_javadoc

Enables support for JavaDoc-style comments (comments with a second asterisk at the start of the comment instead of an exclamation point).

HeaderDoc::parseIfElse

Enables parsing of a bit more of the C programming language to support nonstandard (external) uses of the parser.

HeaderDoc::parsing_man_pages

Magic flag used when parsing manual page declarations.

HeaderDoc::perHeaderIgnoreFuncMacros

Deprecated.

HeaderDoc::perHeaderIgnorePrefixes

Deprecated.

HeaderDoc::perHeaderIncludes

A list of #include directives in the current header.

HeaderDoc::perHeaderRanges

A list of line numbers where CPP #include and #if directives appear.

HeaderDoc::perlClassChange

Provides an out-of-band way for the block parser to change the main API owner at the top level of HeaderDoc.

HeaderDoc::process_everything

Storage for the -E flag.

HeaderDoc::reverse_match

The specific value that causes HeaderDoc to treat the != token as a == token due to consistent eccentricities in what is being parsed.

HeaderDoc::skiplist

The skiplist file.

HeaderDoc::skipNextPDefine

Disables adding the next #definedeclaration to the C preprocessor macro set.

HeaderDoc::sort_entries

Storage for the -u (unsorted) flag.

HeaderDoc::specified_config_file

The configuration file path specified by the -cflag.

HeaderDoc::styleImports

Storage for the styleImports value from the config file.

HeaderDoc::styleSheetExtras

Storage for the contents of the file described in the styleSheetExtrasFile field of the config file.

HeaderDoc::sublang

Global variable where the language info for the header currently being parsed is stored.

HeaderDoc::superclassName

Storage for the superclassName value from the config file.

HeaderDoc::suppress_local_variables

Tells HeaderDoc to suppress local variable documentation.

HeaderDoc::suppressDefaultJavaScript

Storage for the suppressDefaultJavaScript value from the config file.

HeaderDoc::suppressDefaultStyles

Storage for the suppressDefaultStyles value from the config file.

HeaderDoc::testdir

The HeaderDoc test suite location.

HeaderDoc::testmode

Storage for the -T flag.

HeaderDoc::tocStyleImports

Storage for the tocStyleImports value from the config file.

HeaderDoc::truncate_inline

Controls whether to include the body of macros or not.

HeaderDoc::twig_available

Deprecated.

HeaderDoc::uniquenumber

A counter used for generating UUIDs for inherited content.

HeaderDoc::use_iframes

Storage for the -F flag.

HeaderDoc::use_styles

Enables emission of various stylesheet bits.

headerdoc_strip

Storage for the -s flag.

HeaderDoc_Version

The version number of the HeaderDoc suite.

inputFiles

The array of input files to be procesed.

isMacOS

If running in MacPerl in Mac OS 9, contains 1; normally 0.

lang

Language currently being parsed.

man_output

Storage for the -m flag.

pathSeparator

Normally "/", but ":" if running in MacPerl in Mac OS 9.

printVersion

Storage for the -v flag.

quietLevel

Storage for the -q flag.

regenerate_headers

Storage for the -r flag (not yet implemented).

reprocess_input

In practice, this goes high whenever HeaderDoc encounters an @ignore or @ignorefuncmacro tag in an @header comment.

specifiedOutputDir

Storage for the -o flag.

use_stdout

Storage for the -P flag. Also set for the -f flag.

VERSION

The revision control revision number for this script.

xml_output

Storage for the -X flag. Also set for the -m flag.

debugging

Storage for the -d flag.

my $debugging = 0;  

doxytag_output

Storage for the -x flag.

my $doxytag_output;  

doxyTagFiles

Temp storage for list of temp files.

my @doxyTagFiles;  

function_list_output

Storage for the -f flag.

my $function_list_output;  

functionGroup

The name of the current function group.

my $functionGroup = "";  

Discussion

Set by the @functiongroup tag. Reset to empty upon changing to a new header. (If empty, the value of HeaderDoc::globalGroup is used instead.

HeaderDoc::AccessControlState

The current access control state used and modified by the parser.

$HeaderDoc::AccessControlState = "";  

Discussion

This should probably be passed around through arguments, but for now, it is't.

HeaderDoc::add_link_requests

Disables link requests in declarations (-l flag).

$HeaderDoc::add_link_requests = 1;  

Discussion

By default, HeaderDoc inserts link requests into the declarations in HTML output. If you have no interest in declaration linking, you can turn this off by passing the -l flag on the command line. Doing so clears this variable to 0.

HeaderDoc::align_columns

Storage for the -a flag.

$HeaderDoc::align_columns = 1;  

HeaderDoc::allow_multi

Determines whether to treat commented #if/#ifdef blocks as blocks of related functions.

$HeaderDoc::allow_multi = 0;  

Discussion

Set to 1 by default. Set to 0 if the -E flag is passed (unless the language does not support that flag).

HeaderDoc::appleRefUsed

A hash of all API reference markers for minir API elements emitted so far.

%HeaderDoc::appleRefUsed = ();  

Discussion

Used to prevent anyAPI reference markers from being emitted when a documentation block that describes a declaration with multiple names gets emitted a second (or subsequent) time.

HeaderDoc::auto_availability

Storage for the --auto-availability flag.

$HeaderDoc::auto_availability = 0;  

Discussion

By default, HeaderDoc ignores #if directives with Apple-provided availability macros. This flag enables that support by setting this value to 1.

HeaderDoc::availability_defs

A hash table mapping availability macros to the text that describes them.

%HeaderDoc::availability_defs = ();  

Discussion

Used in the block parser to get a human-readable string that describes the availability of the current declaration.

HeaderDoc::availability_has_args

A hash table mapping availability macros to whether or not the macro declaration takes a parenthesized argument list.

%HeaderDoc::availability_has_args = ();  

Discussion

Used in the block parser to determine whether to strip off the subsequent parenthetical code or not.

HeaderDoc::c_compiler

The default C compiler.

$HeaderDoc::c_compiler = "/usr/bin/gcc";  

Discussion

By default, HeaderDoc uses /usr/bin/gcc to calculate the values of complex #define macros. This can be overridden with the cCompiler field in the HeaderDoc config file.

HeaderDoc::ClassAsComposite

Storage for the -C flag.

$HeaderDoc::ClassAsComposite = 0;  

HeaderDoc::cppArgHashList

A list of C preprocessor argument hashes for the current header.

@HeaderDoc::cppArgHashList = ();  

Discussion

This gets reset for each header. HeaderDoc::BlockParse::CPP_ARG_HASH.

HeaderDoc::cppHashList

A list of C preprocessor token hashes for the current header.

@HeaderDoc::cppHashList = ();  

Discussion

This gets reset for each header. For more info, see the documentation for HeaderDoc::BlockParse::CPP_HASH.

HeaderDoc::CurLine

The current line number being parsed.

$HeaderDoc::CurLine = 0;  

Discussion

Used as an out-of-band way to get this information into the parse tree. Should ideally be an argument when each parse tree node is being created, but that isn't nearly as easy as it sounds.

HeaderDoc::currentClass

Used to set the owning class when processing embedded API symbols.

$HeaderDoc::currentClass = undef;  

HeaderDoc::custom_tags

A reference to a hash of non-standard tags to allow.

$HeaderDoc::custom_tags = undef;  

Discussion

Normally, HeaderDoc converts unknown tags to text. You can add custom tags to the list of allowed tags by listing them in the customTags field in the HeaderDoc config file. The hash reference in this variable lists those tags.

HeaderDoc::datefmt

The date format used for date stamps.

$HeaderDoc::datefmt = $config{
    "dateFormat"
};  

Discussion

Value comes from the dateFormat field in the config file.

HeaderDoc::debugAllocations

Turns on debug output when objects are allocated and released.

$HeaderDoc::debugAllocations = 0;  

HeaderDoc::debugFile

Set to the name of a file to tell HeaderDoc to enable debugging when processing that file.

$HeaderDoc::debugFile = "";  

Discussion

Only active if HeaderDoc::fileDebug is nonzero.

HeaderDoc::defaultHeaderComment

The default comment in the right side if a header or class lacks a discussion.

$HeaderDoc::defaultHeaderComment = "Use the links in the table of contents to the left to access the documentation.<br>\n";  

HeaderDoc::document_internal

Enable internal documentation.

$HeaderDoc::document_internal = 0;  

Discussion

Storage for the --document-internal flag.

HeaderDoc::dumb_as_dirt

Deprecated.

$HeaderDoc::dumb_as_dirt = 1;  

Discussion

Storage for the -b flag. This flag uses parser functionality that is no longer maintained. It may or may not work, and you should not count on it to continue working. It was primarily intended as a way of checking parser behavior when the colorizer code was nascent.

HeaderDoc::enable_cpp

Storage for the -p or --enable-cpp flag.

$HeaderDoc::enable_cpp = 0;  

HeaderDoc::enable_macro_filter

Set if any -D or -U flags are passed on the command line.

$HeaderDoc::enable_macro_filter = 1;  

Discussion

This enables and disables the C preprocessor filtering portions.

HeaderDoc::enable_reverse_match

Determines whether the macro filter code should treat the != token as a == token due to consistent eccentricities in what is being parsed.

$HeaderDoc::enable_reverse_match = 0;  

Discussion

HeaderDoc never uses this feature. It is provided entirely for other (internal) tools that use the same code for very different purposes.

See Also

HeaderDoc::enableParanoidWarnings

Storage for the -Q (disquiet) flag.

$HeaderDoc::enableParanoidWarnings = 0;  

HeaderDoc::exclude_patterns

The list of filename patterns to exclude when producing documentation.

@HeaderDoc::exclude_patterns = ();  

Discussion

Obtained from the file specified by the -e flag.

HeaderDoc::exitstatus

The exit status. Changed to nonzero whenever an error occurs.

$HeaderDoc::exitstatus = 0;  

HeaderDoc::explicit_toc_format

Storage for the tocformat value from the config file.

$HeaderDoc::explicit_toc_format = undef;  

HeaderDoc::externalStyleSheets

Storage for the externalStyleSheets value from the config file.

$HeaderDoc::externalStyleSheets = undef;  

HeaderDoc::externalTOCStyleSheets

Storage for the externalTOCStyleSheets value from the config file.

$HeaderDoc::externalTOCStyleSheets = undef;  

HeaderDoc::ExtraAppleWarnings

Flags certain XML tags as illegal due to Apple-internal constraints.

$HeaderDoc::ExtraAppleWarnings = 0;  

HeaderDoc::fileDebug

Set to 1 if you need to enable lots of debugging for a single file.

$HeaderDoc::fileDebug = 0;  

Discussion

Most of the time, when debugging, you can get by with processing a single file. When debugging subtle C preprocessing bugs or other subtle misbehavior, however, it is occasionally necessary to process a lot of files to reproduce the bug.

This flag allows you to leave debugging off until you get to a particular file, then turn it on temporarily for the duration of that file.

This flag must be used in conjunction with HeaderDoc::debugFile.

HeaderDoc::filter_macro_definition_state

A hash of macro definition states passed in on the command line that are interpreted by the macro filter engine.

%HeaderDoc::filter_macro_definition_state = ();  

Discussion

Legal values are:

1

Value we want defined to a particular value (-D flag specified).

-1

Value we want to be explicitly undefined (-U flag specified).

0

Don't care. (Default behavior for any token.)

This variable is used only if -D or -U is passed on the command line (which, in turn, sets the variable HeaderDoc::filter_macro_definition_state to 1).

HeaderDoc::filter_macro_definition_value

A hash of macro values passed in on the command line that are interpreted by the macro filter engine.

%HeaderDoc::filter_macro_definition_value = ();  

Discussion

This hash contains the actual numerical values passed in on the command line. If no value is specified, the value defaults to 1.

This variable is used only if -D or -U is passed on the command line (which, in turn, sets the variable HeaderDoc::filter_macro_definition_state to 1).

For explicitly undefined values (-U), this value is unimportant and should be left blank.

HeaderDoc::flagDashC

Storage for the -C flag. Set to -1 if flag is set.

$HeaderDoc::flagDashC = undef;  

Discussion

This flag is only supported when combined with the older TOC formats (-F flag).

HeaderDoc::flagDashF

Storage for the -F flag (legacy frames output mode).

$HeaderDoc::flagDashF = undef;  

HeaderDoc::force_parameter_tagging

Enables strict parameter taggint warnings (-t flag).

$HeaderDoc::force_parameter_tagging = 0;  

HeaderDoc::FreezeThaw_available

Indicates whether the FreezeThaw Perl module is available.

$HeaderDoc::FreezeThaw_available = 0;  

Discussion

Not all Mac OS X versions have this. It's in 10.5 and later. For backwards compatibility, this code does a check here and doesn't allow the test code (-T flag) to run if it isn't available.

HeaderDoc::globalGroup

The name of the current group.

$HeaderDoc::globalGroup = "";  

Discussion

Set by the @group tag. Reset to empty upon changing to a new header.

HeaderDoc::groupright

Sorts content in the right side (content) pane by group.

$HeaderDoc::groupright = 0;  

HeaderDoc::HeaderFileCPPArgHashHash

Hash of argument lists for C preprocessor macros.

%HeaderDoc::HeaderFileCPPArgHashHash = ();  

Discussion

This hash is a copy of one of the C preprocessor internal hashes. It is returned to the top-level code by a call to getAndClearCPPHash(), and is then merged with the hashes from any headers that the current header includes.

See

HeaderDoc::HeaderFileCPPHashHash

Hash of C preprocessor token hashes for files processed to date.

%HeaderDoc::HeaderFileCPPHashHash = ();  

Discussion

This hash is a copy of one of the C preprocessor internal hashes. It is returned to the top-level code by a call to getAndClearCPPHash(), and is then merged with the hashes from any headers that the current header includes.

In addition to storing the values for future merges, this copy of the hash is used to determine whether a header file has been processed already for the purposes of determining whether or not to merge in C preprocessor macro definitions.

See

HeaderDoc::headerObject

Global header object for the header currently being parsed.

$HeaderDoc::headerObject = undef;  

Discussion

This should eventually go away.

HeaderDoc::hidetokens

Indicates that all token objects should be marked hidden.

$HeaderDoc::hidetokens = 0;  

Discussion

The block parser uses this variable as an out-of-band way to pass the "hide node" flag data to the parse tree package.

Ideally, this should eventuallly go away and should be replaced by changes to every place where a new node gets created, but that isn't nearly as easy as it sounds.

HeaderDoc::idl_language

The API reference language for IDL file content.

$HeaderDoc::idl_language = "idl";  

Discussion

An IDL file contains an interface description in an abstract interface description language (hence the abbreviation). Thus, the actual interfaces could be for any programming language.

By default, IDL file API references (apple_ref symbol markers) are emitted using idl as the language name, but you can override this by specifying a different value for the IDLLanguage field in the HeaderDoc config file.

HeaderDoc::ignore_apiowner_names

Storage for the -n and -N flags.

$HeaderDoc::ignore_apiowner_names = 0;  

HeaderDoc::ignore_apiuid_errors

Set to true when HeaderDoc should suppress warnings about API reference conficts, object name changes, and so on.

$HeaderDoc::ignore_apiuid_errors = 0;  

Discussion

This is set to 1 when HeaderDoc is deliberately making a change to an object that would normally trigger a warning. Do not set this indiscriminately, as doing so can mask actual errors in source content that result in incorrect output.

HeaderDoc::ignorePrefixes

Deprecated.

%HeaderDoc::ignorePrefixes = ();  

Discussion

Storage for an old scheme to ignore junk CPP tokens at the start of line. This holds the value of the ignorePrefixes field in the config file.

The currently recommended way to do this is with the C preprocessor on the command line (-D FOO="") or in code.

HeaderDoc::IncludeSuper

Storage for the -S flag.

$HeaderDoc::IncludeSuper = 1;  

HeaderDoc::insert_header

Storage for the -H flag.

$HeaderDoc::insert_header = 0;  

HeaderDoc::interpret_case

Determines whether the macro filter code attempts to handle switch and case statements.

$HeaderDoc::interpret_case = 0;  

Discussion

HeaderDoc never uses this feature. It is provided entirely for other (internal) tools that use the same code for very different purposes.

HeaderDoc::introductionName

Storage for the introductionName configuration file field.

$HeaderDoc::introductionName = "Introduction";  

HeaderDoc::lang

Global variable where the language family info for the header currently being parsed is stored.

$HeaderDoc::lang = undef;  

Discussion

Historical versions of HeaderDoc used this in place of passing this information around through the code. This has been corrected in current versions, but the blockParse and blockParseOutside functions still support falling back to this and HeaderDoc::sublang for backwards compatibility. (This backward compatibility is temporary, however.)

HeaderDoc::man_section

Storage for the -M flag.

$HeaderDoc::man_section = "3";  

HeaderDoc::maxDecLen

Maximum line length for wrapping declarations.

$HeaderDoc::maxDecLen = 60;  # Wrap functions, etc. if declaration longer than this length 

Discussion

You can override this with the wrapAtColumn field in the configuration file.

HeaderDoc::modulesPath

The location from which the HeaderDoc modules were loaded.

$HeaderDoc::modulesPath = $INC{
    'HeaderDoc/ParseTree.pm'
};  

Discussion

This variable is populated automatically.

HeaderDoc::nameFromAPIRefReturnsOnlyName

Storage for the bareNamesFromAPIRefs flag

$HeaderDoc::nameFromAPIRefReturnsOnlyName = 0;  

Discussion

By default, if you use an @link tag and specify only an API reference marker (apple_ref), as a link destination (with no link text), HeaderDoc substitutes a class method call for Objective-C methods and a name in the form classname::methodName for other methods.

If you set this flag to 1, this behavior is disabled for Objective-C methods.

If you set this flag to 2, this behavior is disabled for non-Objective-C methods.

If you set this flag to 3, this behavior is disabled for all methods.

HeaderDoc::namerefs

Used for quickly looking up names of fields in data types by the data type name and field name.

%HeaderDoc::namerefs = ();  

HeaderDoc::newTOC

New TOC style variable.

$HeaderDoc::newTOC = 0;  

Discussion

Set by setTOCFormat.

HeaderDoc::outerNamesOnly

Enables/disables "outer name" type handling (-O flag).

$HeaderDoc::outerNamesOnly = 0;  # storage for -O flag. 

Discussion

By default, HeaderDoc documents all names for type declarations. This flag disables emission of documentation for inner (structure, enumeration, or union) tag names declared inline.

For example, typdef struct a { ... } b; has two names by default: a and b. With the -O flag, only the outer name (b) is emitted in the documentation.

HeaderDoc::parse_javadoc

Enables support for JavaDoc-style comments (comments with a second asterisk at the start of the comment instead of an exclamation point).

$HeaderDoc::parse_javadoc = 0;  

HeaderDoc::parseIfElse

Enables parsing of a bit more of the C programming language to support nonstandard (external) uses of the parser.

$HeaderDoc::parseIfElse = 0;  

Discussion

HeaderDoc itself does not use this functionality.

HeaderDoc::parsing_man_pages

Magic flag used when parsing manual page declarations.

$HeaderDoc::parsing_man_pages = undef;  

Discussion

Set to 1 if (in C) you want a function declaration to end after the closing parenthesis even if there is no trailing semicolon. Do NOT set this for normal parsing; it will break many typedef declarations and similar. This also enables some broken man page detection for deleting lines that say or and and.

Note that HeaderDoc does not actually set this flag. It is used by other tools that share this parser.

HeaderDoc::perHeaderIgnoreFuncMacros

Deprecated.

%HeaderDoc::perHeaderIgnoreFuncMacros = ();  

Discussion

Storage for an old scheme to ignore junk CPP tokens at the start of line. This holds the list of values from @ignorefuncmacro tags.

The currently recommended way to do this is with the C preprocessor in the code itself.

HeaderDoc::perHeaderIgnorePrefixes

Deprecated.

%HeaderDoc::perHeaderIgnorePrefixes = ();  

Discussion

Storage for an old scheme to ignore junk CPP tokens at the start of line. This holds the list of values from @ignore tags.

The currently recommended way to do this is with the C preprocessor on the command line (-D FOO="") or in code.

HeaderDoc::perHeaderIncludes

A list of #include directives in the current header.

%HeaderDoc::perHeaderIncludes = ();  

HeaderDoc::perHeaderRanges

A list of line numbers where CPP #include and #if directives appear.

%HeaderDoc::perHeaderRanges = ();  

Discussion

Used for determining which C preprocessor directives should be applied to a given block of code.

HeaderDoc::perlClassChange

Provides an out-of-band way for the block parser to change the main API owner at the top level of HeaderDoc.

$HeaderDoc::perlClassChange = undef;  

Discussion

Used to work around the rather odd way Perl's classes are designed. (They have no end, and due to limitations in HeaderDoc, they cannot be parsed as a single block and pulled apart as other languages can.)

Normally, this is empty. When set by the parser, the top-level API owner is reset to that object.

HeaderDoc::process_everything

Storage for the -E flag.

$HeaderDoc::process_everything = 1;  

HeaderDoc::reverse_match

The specific value that causes HeaderDoc to treat the != token as a == token due to consistent eccentricities in what is being parsed.

$HeaderDoc::reverse_match = 0;  

Discussion

HeaderDoc never uses this feature. It is provided entirely for other (internal) tools that use the same code for very different purposes.

See Also

HeaderDoc::skiplist

The skiplist file.

$HeaderDoc::skiplist = "";  

Discussion

If HeaderDoc is processing a single directory as its input, it looks for a file at the top level of that directory called skiplist. If it finds that file, it reads it, and for each line that is not commented out (with a # sign), it adds it into this newline-delimited list.

HeaderDoc later uses this list to determine which files to skip when processing the content. Note that the preferred way to do this is with exclude lists (the -e flag).

HeaderDoc::skipNextPDefine

Disables adding the next #definedeclaration to the C preprocessor macro set.

$HeaderDoc::skipNextPDefine = 0;  

Discussion

Triggered by a @noparse directive in comment. When this directive is encountered, the directive is parsed for documentation purposes, but is not added to the set of macros that affect parsing of other declarations.

HeaderDoc::sort_entries

Storage for the -u (unsorted) flag.

$HeaderDoc::sort_entries = undef;  

Discussion

Set to 0 if flag is set, else 1.

HeaderDoc::specified_config_file

The configuration file path specified by the -cflag.

$HeaderDoc::specified_config_file = "";  

HeaderDoc::styleImports

Storage for the styleImports value from the config file.

$HeaderDoc::styleImports = undef;  

HeaderDoc::styleSheetExtras

Storage for the contents of the file described in the styleSheetExtrasFile field of the config file.

$HeaderDoc::styleSheetExtras = undef;  

HeaderDoc::sublang

Global variable where the language info for the header currently being parsed is stored.

$HeaderDoc::sublang = undef;  

Discussion

Historical versions of HeaderDoc used this in place of passing this information around through the code. This has been corrected in current versions, but the blockParse and blockParseOutside functions still support falling back to this and HeaderDoc::lang for backwards compatibility. (This backward compatibility is temporary, however.)

HeaderDoc::superclassName

Storage for the superclassName value from the config file.

$HeaderDoc::superclassName = "Superclass";  

HeaderDoc::suppress_local_variables

Tells HeaderDoc to suppress local variable documentation.

$HeaderDoc::suppress_local_variables = 0;  

Discussion

By default, a local variable (an @var tag inside a function or method discussion) is emitted on the output. This is desirable for internal documentation purposes, but is undesirable for public documentation purposes.

Passing the -L flag on the command line sets this flag and suppresses the emission of documentation on these local variables.

HeaderDoc::suppressDefaultJavaScript

Storage for the suppressDefaultJavaScript value from the config file.

$HeaderDoc::suppressDefaultJavaScript = 0;  

HeaderDoc::suppressDefaultStyles

Storage for the suppressDefaultStyles value from the config file.

$HeaderDoc::suppressDefaultStyles = 0;  

HeaderDoc::testdir

The HeaderDoc test suite location.

$HeaderDoc::testdir = $HeaderDoc::modulesPath."/../../testsuite";  

Discussion

If HeaderDoc is being run out of a checked out copy. this is the testsuite directory in that checked out copy. Otherwise, this uses the installed path, /usr/share/headerdoc/testsuite

HeaderDoc::testmode

Storage for the -T flag.

$HeaderDoc::testmode = undef;  

HeaderDoc::tocStyleImports

Storage for the tocStyleImports value from the config file.

$HeaderDoc::tocStyleImports = undef;  

HeaderDoc::truncate_inline

Controls whether to include the body of macros or not.

$HeaderDoc::truncate_inline = 0;  

Discussion

By default, HeaderDoc omits the body of macro definitions in the documentation. You can pass the -i flag to include macro bodies in the output. Doing so sets this variable to zero. Omitting the flag sets this variable to 1.

HeaderDoc::twig_available

Deprecated.

$HeaderDoc::twig_available = 0;  

Discussion

Twig isn't installed by default in Mac OS X. This is used in a feature that never got implemented---specifically, parsing modified HeaderDoc XML output and updating the HeaderDoc comments in the headers to allow round-tripping HeaderDoc markup through XML editor tools. (The need for this functionality never materialized. Also, in hindsight, a more lightweight, and more commonly installed XML parser API would also be better.)

HeaderDoc::uniquenumber

A counter used for generating UUIDs for inherited content.

$HeaderDoc::uniquenumber = 0;  

HeaderDoc::use_iframes

Storage for the -F flag.

$HeaderDoc::use_iframes = 1;  

Discussion

Note that this variable may get removed eventually in favor of a more flexible output style variable.

HeaderDoc::use_styles

Enables emission of various stylesheet bits.

$HeaderDoc::use_styles = 0;  

Discussion

Set if certain keys appear (with content) in the config file.

headerdoc_strip

Storage for the -s flag.

my $headerdoc_strip;  

HeaderDoc_Version

The version number of the HeaderDoc suite.

my $HeaderDoc_Version = "8.9";  

inputFiles

The array of input files to be procesed.

my @inputFiles;  

isMacOS

If running in MacPerl in Mac OS 9, contains 1; normally 0.

my $isMacOS;  

lang

Language currently being parsed.

my $lang = "C";  

man_output

Storage for the -m flag.

my $man_output;  

pathSeparator

Normally "/", but ":" if running in MacPerl in Mac OS 9.

my $pathSeparator;  

printVersion

Storage for the -v flag.

my $printVersion;  

quietLevel

Storage for the -q flag.

my $quietLevel;  

regenerate_headers

Storage for the -r flag (not yet implemented).

my $regenerate_headers;  

reprocess_input

In practice, this goes high whenever HeaderDoc encounters an @ignore or @ignorefuncmacro tag in an @header comment.

my $reprocess_input = 0;  

specifiedOutputDir

Storage for the -o flag.

my $specifiedOutputDir;  

use_stdout

Storage for the -P flag. Also set for the -f flag.

my $use_stdout;  

VERSION

The revision control revision number for this script.

my $VERSION = '$Revision: 1334261201 $';  

Discussion

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

xml_output

Storage for the -X flag. Also set for the -m flag.

my $xml_output;