Class: phpDocumentor_IntermediateParser
Source Location: /phpDocumentor/IntermediateParser.inc
Class phpDocumentor_IntermediateParser
Property Summary
array |
$all_packages |
list of all packages encountered while documenting. Used in automatic linking. |
Classes |
$classes |
used to keep track of inheritance at the smartest level possible for a |
array |
$converters |
an array of template names indexed by converter name |
string |
$cur_class |
Name of the class currently being parsed. |
parserData |
$data |
$data contains parsed structures for the current page being parsed |
string |
$lasttype |
type of the last parser Element handled |
false|array |
$packageoutput |
array of packages to parser and output documentation for, if not all packages should be documented |
array |
$package_parents |
Keeps track of packages of classes that have parent classes in another package. Used in automatic linking. |
array |
$privatepages |
Put away a page that has been @ignored or @access private if !$parsePrivate |
mixed |
$private_class |
this variable is used to prevent parsing of elements with an @ignore tag |
array |
$ric |
Stores parsed CHANGELOG/INSTALL/README files |
string |
$type |
type of the current parser Element being handled |
Method Summary
void |
addConverter() |
Add a converter name to use to the list of converters |
void |
addPackageParent() |
If the parent class of $class is in a different package, adds it to the |
void |
addUses() |
Add all the @uses tags from $element to the $uses array so that @usedby |
void |
Convert() |
Interface to the Converter |
void |
handleConst() |
handles post-parsing of class constants |
void |
handleGlobal() |
handles post-parsing of global variables |
void |
handleInclude() |
handles post-parsing of include/require/include_once/include_once |
void |
handlePage() |
handles post-parsing of procedural pages |
void |
handleVar() |
handles post-parsing of class vars |
void |
Output() |
call this method once parsing has completed. |
void |
parsePackagePage() |
Backward-compatibility only, use the new tutorials for more power |
void |
setQuietMode() |
set parsing information output mode (quiet or verbose) |
void |
_guessPackage() |
Guess the package/subpackage based on subdirectory if the --pear option |
Properties
list of all packages encountered while documenting. Used in automatic linking.
Converter::getLink() first checks if an ambiguous link is found in the current package. If not, it then checks in parent packages, and if still not found, uses this array to check in the rest of the packages before giving up API Tags:
used to keep track of inheritance at the smartest level possible for a
dumb computer
an array of template names indexed by converter name
For example, if the default HTMLframesConverter is using the DOM/l0l33t template, the array will be $converters['frames'] = 'DOM/l0l33t'
API Tags:
Name of the class currently being parsed.
It is only used (and only valid) when phpDocumentor_IntermediateParser is parsing a class
$data contains parsed structures for the current page being parsed
In version 1.1+, $data is only used to store the current page information. All handling of documented elements is handled by the ProceduralPages and Classes classes.
the functions which handle output from the Parser
API Tags:
type of the last parser Element handled
This is used in handleDocBlock to determine whether a DocBlock is a page-level DocBlock in conjunction with the parserData::$clean var. A page-level DocBlock is alwaysthe first DocBlock in a file, and must be followed by another DocBlock. The first test is handled by parserData::$clean, which is set to false on the first encounter of an element, and the second test is handled by this variable, which must be equal to "docblock" API Tags:
Used to determine the category for tutorials.
WARNING: If more than one category exists, the last category encountered will overwrite the previous and will raise a big warning
array of packages to parser and output documentation for, if not all packages should be documented
Format: array(package1,package2,...) or false if not set Use this option to limit output similar to ignoring files. If you have some temporary files that you don't want to specify by name but don't want included in output, set a package name for all the elements in your project, and set packageoutput to that name. the default package will be ignored. Parsing speed does not improve. If you want to ignore files for speed reasons, use the ignore command-line option API Tags:
Information Tags:
array of parsed package pages
used by Convert() to convert all package pages into output
Keeps track of packages of classes that have parent classes in another package. Used in automatic linking.
This array is updated by addPackageParent(), which is called in Classes::processChild() to keep track of classes that descend from classes in different packages. In other words, if class foo is in package one, and class bar is in package two, an entry $package_parents['two'] = 'one' will be made. API Tags:
set in Setup.inc.php to the value of the parseprivate commandline
option. If this option is true, elements with an @access private tag will be parsed and displayed
Information Tags:
Put away a page that has been @ignored or @access private if !$parsePrivate
When a page has @access private in its DocBlock, it is placed here instead of in $pages, to allow for proper Class parsing. Since classes and pages are parsed as if they were separate, this array allows public classes on private pages to retrieve information needed about the page that holds the class and to addPageIfNecessary() to the $pages array
this variable is used to prevent parsing of elements with an @ignore tag
API Tags:
used to keep track of all elements in a procedural page. Handles name
conflicts with elegance
Information Tags:
set in Setup.inc.php to the value of the quitemode commandline option.
If this option is true, informative output while parsing will not be displayed (documentation is unaffected)
Information Tags:
Stores parsed CHANGELOG/INSTALL/README files
used to set the output directory
API Tags:
used to set the template base directory
API Tags:
type of the current parser Element being handled
This is used by HandleEvent() to set the $lasttype var, which is used to detect page-level DocBlocks
Methods
phpDocumentor_IntermediateParser phpDocumentor_IntermediateParser(
[string
$title = 'Generated Documentation']
)
|
|
sets up basic data structures
Parameters:
string |
$title: |
Title of generated documentation, passed to Converters |
API Tags:
void addConverter(
string
$output, string
$name, string
$template
)
|
|
Add a converter name to use to the list of converters
Sets up the $converters array. }
Parameters:
string |
$output: |
output format (HTML, PDF, XML). Must be all caps |
string |
$name: |
Converter name (frames, for example, is the name of HTMLframesConverter) |
string |
$template: |
template to use, should be a relative path to the templates dir (like DOM/default) |
adds a processed descendant of parserElement to the $pages array or $privatepages array
This function expects the page to exist in either $pages or $privatepages. It calls the parserData::addElement() method to add $element to the page.
Parameters:
parserElement |
$element: |
this will actually be a descendant of parserElement |
string |
$path: |
|
If the parent class of $class is in a different package, adds it to the
$package_parents array
Parameters:
Replaces the parserPage represented by $this->pages[$path] with $page
Called by addPageIfNecessary(), handleDocBlock() and ProceduralPages::setupPages(), this method first checks to see if the page has been added. If not, it assumes that the page has either been @ignored or set with @access private with --parseprivate off, and returns addPrivatePage(). Otherwise, it sets the pages[$path] to be the parserPage $page and sets the package and subpackage to that of $page
Parameters:
parserPage |
$page: |
|
string |
$path: |
full path to the file |
API Tags:
void addPageIfNecessary(
string
$path,
&$class
)
|
|
add a new parserPage to the $pages array if none is found
This method is used when a page has been @ignored or marked with @access private, and a public class is in the page (a class with no @access private in its DocBlock). The method first creates a new page in the $pages array and then copies path information, and calls addPage() to set up packages
Parameters:
string |
$path: |
full path of page |
|
&$class: |
|
void addPrivatePage(
parserPage
$page, string
$path
)
|
|
Adds a parserPage element to the parserData element in $this->privatepages[$path]
Performs a similar function to addPage, but adds to the $privatePages array
Parameters:
parserPage |
$page: |
|
string |
$path: |
full path to the page |
API Tags:
Add all the @uses tags from $element to the $uses array so that @usedby
virtual tags can be added
Parameters:
parserElement |
$element: |
descendant of parserElement |
string |
$path: |
full path to the file |
API Tags:
int ClasselementCmp(
mixed
$a, mixed
$b
)
|
|
does a natural case sort on two class elements (either parserClass, parserMethod or parserVar
Parameters:
API Tags:
See: | generateElementIndex() |
void Convert(
$title,
$converter
)
|
|
Interface to the Converter
This function simply passes $pages and package_pages to the walk() method, and then calls the Output() method. Note that Output() is not required to do anything, and in fact doesn't in HTMLframesConverter.
Parameters:
API Tags:
int elementCmp(
mixed
$a, mixed
$b
)
|
|
does a natural case sort on two parserElement descendants
Parameters:
API Tags:
See: | generateElementIndex() |
handles post-parsing of classes
This function sets $data->clean to false to tell the phpDocumentor_IntermediateParser that a page-level DocBlock can't be found after this point on this page. It sets $cur_class to its name, and if an @ignore tag is found in the DocBlock, it sets $private_class to true, to prevent post-parsing of any of the class's vars or methods. Then it checks for the existence of a package page for the class's package
Parameters:
void handleConst(
integer
$event, parserVar
$data
)
|
|
handles post-parsing of class constants
This function aligns $data's $path var and packages to match the parent object
Parameters:
handles post-parsing of defines
This function sets $data->clean to false to tell the phpDocumentor_IntermediateParser that a page-level DocBlock can't be found after this point on this page. It then sets the package to be the same as the page and adds itself to the ProceduralPages class
Parameters:
handles post-parsing of DocBlocks
This function sets $last to the DocBlock represented by $data, to allow the next documentable element passed to phpDocumentor_IntermediateParser to link the DocBlock into its $docblock property. This function also checks for two special cases of DocBlocks: - First DocBlock in the file contains a @package tag
- First DocBlock in the file is immediately followed by another
DocBlock
In both cases, the function extracts this tag and uses it as the page-level package. If the @package tag is in the DocBlock of an element (function, global variable, whatever) that isn't a page-level DocBlock, a warning will be raised to notify the author that a @package tag belongs in a page-level DocBlock.New in version 1.2.2, if the first DocBlock in a file contains a @package tag, it is a page-level DocBlock. If the DocBlock is page-level, it is processed with _processPageLevelDocBlock Finally, the function replaces the old parserPage in parserData::$data->parent with the new one containing information from the DocBlock by calling addPage(), and checks for package-level docs.
Parameters:
void HandleEvent(
integer
$event, mixed
$data
)
|
|
called via Parser::parse() and Parser's inherited method Publisher::publishEvent()
$event is one of the PHPDOC constants from Parser.inc. If it is not PHPDOCUMENTOR_EVENT_NEWSTATE, then a function name is retrieved from the $event_handlers array and called to handle the $data
Parameters:
API Tags:
Global: | array $_phpDocumentor_setting$phpDocumentor_DefaultPackageName: we use 'sourcecode' to determine whether to highlight the source
of the current file if it has no file-level docblock |
handles post-parsing of functions
This function sets $data->clean to false to tell the phpDocumentor_IntermediateParser that a page-level DocBlock can't be found after this point on this page. It then sets the package to be the same as the page, aligns the docblock's @param, @global, and @staticvar tags with the information parsed from the function source code. If source code has been parsed by a {@source} tag, the source is added to its docblock, and then the parserFunction adds itself to the ProceduralPages class
Parameters:
handles post-parsing of global variables
This function sets $data->clean to false to tell the phpDocumentor_IntermediateParser that a page-level DocBlock can't be found after this point on this page. It then sets the package to be the same as the page, and adds itself to the ProceduralPages class
Parameters:
handles post-parsing of include/require/include_once/include_once
This function sets $data->clean to false to tell the phpDocumentor_IntermediateParser that a page-level DocBlock can't be found after this point on this page. It then sets the package to be the same as the page, and adds itself to the ProceduralPages class
Parameters:
handles post-parsing of class methods
This function first aligns $data's path and package to match the parent object, and also aligns the docblock's @param, @global, and @staticvar tags with the information parsed from the method source code. It also checks to see if the method is a constructor and sets the $isConstructor flag. If source code has been parsed by a {@source} tag, the source is added to its docblock Finally, it adds the method to the Classes class.
Parameters:
handles post-parsing of Package-level documentation pages.
sets the $package_pages[$data->package] to $data
Parameters:
void handlePage(
integer
$event, parserPage
$data
)
|
|
handles post-parsing of procedural pages
this event is called at the start of a new page, before the Parser knows whether the page will contain any procedural pages or not
Parameters:
handle post-parsing of Tutorials.
This adds the parsed tutorial to the tutorial tree
Parameters:
API Tags:
Uses: | $tutorials - sets the value of tutorials to parameter $data |
Information Tags:
void handleVar(
integer
$event, parserVar
$data
)
|
|
handles post-parsing of class vars
This function sets up a @var tag if none is found, and aligns $data's $path var and packages to match the parent object
Parameters:
void Output(
[
$title = "Generated Documentation"]
)
|
|
call this method once parsing has completed.
This method calls the private methods fixClasses and fixProcPages, both of which adjust inheritance and package information based on complicated post-parsing rules described in ProceduralPages::setupPages() and Classes::Inherit(). Then, it sorts elements of the $pages array and calls Convert for each Converter in the $converters array
Parameters:
API Tags:
void parsePackagePage(
string
$package, string
$path
)
|
|
Backward-compatibility only, use the new tutorials for more power
Parameters:
string |
$package: |
package name of package file to parse |
string |
$path: |
directory of file that contains package name |
Information Tags:
void setParsePrivate(
bool
$parse
)
|
|
set display of elements marked with @access private
If set to true, elements will be displayed
Parameters:
void setQuietMode(
bool
$quietMode
)
|
|
set parsing information output mode (quiet or verbose)
If set to false, no parsing information (parsing /php/file/thisfile.php, Converting etc.) will be displayed. Useful for cron jobs
Parameters:
void setTargetDir(
string
$dir
)
|
|
Sets the output directory
Parameters:
string |
$dir: |
the output directory |
void setTemplateBase(
string
$dir
)
|
|
Sets the template base directory
Parameters:
string |
$dir: |
the template base directory |
Information Tags:
void _guessPackage(
string
$path, template-ready
$sourceloc
)
|
|
Guess the package/subpackage based on subdirectory if the --pear option
A file in pear/dir/file.php will be in package "dir." A file in pear/dir/subdir/file.php will be in package "dir," subpackage "subdir."
Parameters:
string |
$path: |
full path of file |
template-ready |
$sourceloc: |
source location Program_Root/dir/file.php |
API Tags:
Information Tags:
|
|