HeaderDoc::DocReference

Declared In:

Introduction

Describes the properties of an API or document reference (apple_ref).

Discussion

A data structure used for holding references to documents in gatherHeaderDoc.

Each object contains the name of a header, class, or API symbol, along with its path, its unique identifier (API refeference) and bits of related information like the symbol's abstract, discussion, and declaration (where available).

Member Functions

_initialize: Initializes an instance of a DocReference object.
abstract: Gets/sets the abstract associated with this doc reference.
dbprint: Prints a DocReference object for debugging purposes.
declaration: Gets/sets the discussion associated with this doc reference.
discussion: Gets/sets the discussion associated with this doc reference.
getCorrectWhoIsInfo: Splits up the results from whois, prioritizing single entries over collective ones and earlier collective results over later ones.
group: Gets/sets the group associated with this doc reference.
hidden: Prevents C API reference symbols from showing up in man page output.
isDoc: Returns whether this doc reference has a "doc" API reference.
isInCache: Returns whether a UID has been seen.
language: Gets/sets the language associated with this doc reference.
mansrc: Gets/sets the mansrc value associated with this doc reference.
mpname: Sets the man page name associated with this doc reference.
name: Gets/sets the name associated with this doc reference.
new: Creates a new DocReference object.
outputformat: Gets/sets the output format for this doc reference.
path: Gets/sets the path associated with this doc reference.
printObject: Alias to dbprint.
pushed: Gets/sets the "pushed" state for this doc reference.
quoteForGrep: Quotes a string for passing to grep.
quoteForWhatIs: Quotes a string for passing to whatis.
seealso
shortname: Gets/sets the short name associated with this doc reference.
translateManRef: Maps a man page doc reference to a C reference.
type: Gets/sets the type associated with this doc reference.
uid: Gets/sets the uid associated with this doc reference.

_initialize

Initializes an instance of a DocReference object.

sub _initialize

Parameters

self: The object to initialize.

abstract

Gets/sets the abstract associated with this doc reference.

sub abstract

Parameters

self: The DocReference object.
abstract: The abstract to set. (Optional.)

Discussion

For manual pages, this goes out and requests the abstract using whois.

dbprint

Prints a DocReference object for debugging purposes.

sub dbprint

Parameters

self: The object to initialize.

declaration

Gets/sets the discussion associated with this doc reference.

sub declaration

Parameters

self: The DocReference object.
discussion: The discussion to set. (Optional.)

discussion

Gets/sets the discussion associated with this doc reference.

sub discussion

Parameters

self: The DocReference object.
discussion: The discussion to set. (Optional.)

getCorrectWhoIsInfo

Splits up the results from whois, prioritizing single entries over collective ones and earlier collective results over later ones.

sub getCorrectWhoIsInfo

group

Gets/sets the group associated with this doc reference.

sub group

Parameters

self: The DocReference object.
group: The group to set. (Optional.)

hidden

Prevents C API reference symbols from showing up in man page output.

sub hidden

isDoc

Returns whether this doc reference has a "doc" API reference.

sub isDoc

Parameters

self: The DocReference object.

isInCache

Returns whether a UID has been seen.

sub isInCache

language

Gets/sets the language associated with this doc reference.

sub language

Parameters

self: The DocReference object.
language: The language to set. (Optional.)

mansrc

Gets/sets the mansrc value associated with this doc reference.

sub mansrc

Parameters

self: The DocReference object.
type: The mansrc value to set. (Optional.)

Discussion

The mansrc value refers to the part of a doc navigator comment after the "mansrc=" part. It is used to hold information about which set of man pages a man page came from (e.g. base, server, etc.).

mpname

Sets the man page name associated with this doc reference.

sub mpname

Parameters

self: The DocReference object.

Discussion

For doc references of man pages, this returns the name in the standard man page format, e.g. name(number). For non-man-page references, this returns an empty string.

name

Gets/sets the name associated with this doc reference.

sub name

Parameters

self: The DocReference object.
name: The name to set. (Optional.)

new

Creates a new DocReference object.

sub new

Parameters

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

outputformat

Gets/sets the output format for this doc reference.

sub outputformat

Parameters

self: The DocReference object.
outputformat: The output format value to set. (Optional.)

path

Gets/sets the path associated with this doc reference.

sub path

Parameters

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

printObject

Alias to dbprint.

sub printObject

Parameters

self: The object to initialize.

pushed

Gets/sets the "pushed" state for this doc reference.

sub pushed

Parameters

self: The DocReference object.
pushed: The pushed state to set. (Optional.)

Discussion

The pushed state refers to whether the doc reference has already been pushed into the array of doc references in gatherHeaderDoc or not. This is needed because subsequent discussions and abstracts get folded back into the same doc reference, and you don't want to end up pushing it twice.

quoteForGrep

Quotes a string for passing to grep.

sub quoteForGrep

Parameters

string: The string to quote.

quoteForWhatIs

Quotes a string for passing to whatis.

sub quoteForWhatIs

Parameters

string: The string to quote.

shortname

Gets/sets the short name associated with this doc reference.

sub shortname

Parameters

self: The DocReference object.
shortname: The short name to set. (Optional.)

Discussion

The short name refers to the name of a framework (without the trailing ".framework" or any other path parts).

translateManRef

Maps a man page doc reference to a C reference.

sub translateManRef

Parameters

ref: The input doc reference.

Discussion

Uses the docRefNameToUIDCache cache, which is populated in uid.

type

Gets/sets the type associated with this doc reference.

sub type

Parameters

self: The DocReference object.
type: The type to set. (Optional.)

Discussion

The type refers to the part of a doc navigator comment after the "headerDoc=" part.

uid

Gets/sets the uid associated with this doc reference.

sub uid

Parameters

self: The DocReference object.
uid: The uid to set. (Optional.)

Return Value

Returns any existing doc reference object for the specified doc ID from the current file.

Discussion

If called repeatedly, any non-doc apple_ref will stick with higher precedence than any doc apple_ref.

Member Data

ABSTRACT

The @abstract associated with this doc reference.

DECLARATION

The declaration (code) associated with this doc reference.

DISCUSSION

The @discussion associated with this doc reference.

GROUP

The index group for this doc reference. (From the @indexgroup tag.)

HeaderDoc::DocReference::VERSION

The revision control revision number for this module.

LANGUAGE

The language part of the UID for this doc reference.

MANSRC

Holds information about which set of manual pages a man page came from. Access this variable with the mansrc function.

NAME

The "long name" (name specified in a tag such as @header, @function, etc.

OUTPUTFORMAT

Unused.

PATH

The filesystem path to the file containing this doc reference.

PUSHED

Set to 1 when the doc reference has already been added to the doc reference array so that it doesn't get added multiple times when the discussion and abstract are located.

SHORTNAME

The "short name" (code symbol name or raw filename) for this doc reference.

TYPE

The type part of the UID (e.g. cl for class).

See the HeaderDoc User Guide for more information about API symbol markers.

UID

The API reference (UID) for this doc reference, e.g. //apple_ref/c/func/foo.

See the HeaderDoc User Guide for more information about API symbol markers.

ABSTRACT

The @abstract associated with this doc reference.

$self->{ABSTRACT}

DECLARATION

The declaration (code) associated with this doc reference.

$self->{DECLARATION}

DISCUSSION

The @discussion associated with this doc reference.

$self->{DISCUSSION}

GROUP

The index group for this doc reference. (From the @indexgroup tag.)

$self->{GROUP}