Source for file IntermediateParser.inc
Documentation is available at IntermediateParser.inc
* The phpDocumentor_IntermediateParser Class
* The Intermediary Data Parser (intermediate between Parse and Converter)
* phpDocumentor :: automatic documentation generator
* Copyright (c) 2002-2006 Gregory Beaver
* This library is free software; you can redistribute it
* and/or modify it under the terms of the GNU Lesser General
* Public License as published by the Free Software Foundation;
* either version 2.1 of the License, or (at your option) any
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* @author Gregory Beaver <cellog@php.net>
* @copyright 2002-2006 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
/** The phpDocumentor_IntermediateParser Class
* This class performs the work of organizing raw data from the parser in the
* format of descendants of the {@link parserElement} class. This is also where
* processing of package pages occurs, in
* {@link phpDocumentor_IntermediateParser::handleClass()} for class-level
* packages and {@link phpDocumentor_IntermediateParser::handleDocBlock()} for
* Most of the work of this parser goes to matching up
* DocBlocks with the elements that they are documenting. Since DocBlocks are
* passed before the element they document, the last DocBlock is stored in
* {@link phpDocumentor_IntermediateParser::$last} and then placed into the
* $docblock parameter of the parserElement
* @copyright 2002 Gregory Beaver
* 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 {@link 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
* Name of the class currently being parsed.
* It is only used (and only valid) when phpDocumentor_IntermediateParser is
* type of the current parser Element being handled
* This is used by {@link HandleEvent()} to set the {@link $lasttype} var,
* which is used to detect page-level DocBlocks
* set in {@link 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
* @tutorial phpDocumentor.howto.pkg#using.command-line.parseprivate
* this variable is used to prevent parsing of elements with an @ignore tag
* used to set the output directory
* used to set the template base directory
* array of parsed package pages
* used by {@link Convert()} to convert all package pages into output
* @var array array of all {@link parserData} containing page information
* Put away a page that has been @ignored or @access private if
* When a page has @access private in its DocBlock, it is placed here
* instead of in {@link $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 {@link addPageIfNecessary()} to the
* Keeps track of packages of classes that have parent classes in another
* package. Used in automatic linking.
* This array is updated by {@link addPackageParent()}, which is called in
* {@link 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.
* @var array Format: packagename => parentpackagename
* @see Converter::getLink()
* Used to determine the category for tutorials.
* <b>WARNING:</b> If more than one category exists, the last category
* encountered will overwrite the previous and will raise a big warning
* @var array Format: packagename => categoryname
* list of all packages encountered while documenting. Used in automatic
* 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
* @var array Format: array(packagename => 1, packagename => 1,...)
* @see Converter::getLink()
* array of packages to parser and output documentation for, if not all
* packages should be documented
* array(package1,package2,...)<br />
* 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
* @tutorial phpDocumentor.howto.pkg#using.command-line.packageoutput
* the functions which handle output from the {@link Parser}
* @see handleEvent(), handleDocBlock(), handlePage(), handleClass()
* @see handleDefine(), handleFunction(), handleMethod(), handleVar()
* @see handlePackagePage(), handleInclude(), handleTutorial()
'docblock' => 'handleDocBlock',
'class' => 'handleClass',
'define' => 'handleDefine',
'function' => 'handleFunction',
'method' => 'handleMethod',
'const' => 'handleConst',
'packagepage' => 'handlePackagePage',
'include' => 'handleInclude',
'global' => 'handleGlobal',
'tutorial' => 'handleTutorial',
* $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
* {@link ProceduralPages} and {@link Classes} classes.
* set in {@link Setup.inc.php} to the value of the quitemode commandline
* If this option is true, informative output while parsing will not be
* displayed (documentation is unaffected)
* @tutorial phpDocumentor.howto.pkg#using.command-line.quiet
* set in {@link Setup.inc.php} to the value of the undocumentedElementWarnings commandline
* If this option is true, warnings about certain elements (classes, methods)
* that are not documented with DocBlocks will be shown while parsing,
* and will also be displayed in the errors.html page
* (other documentation is unaffected)
* @tutorial phpDocumentor.howto.pkg#using.command-line.undocumentedelements
* used to keep track of inheritance at the smartest level possible for a
* used to keep track of all elements in a procedural page. Handles name
* conflicts with elegance
* 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
* <code>$converters['frames'] = 'DOM/l0l33t'</code>
* @var array Format: array(Convertername1 => templatename)
* @var string Title of generated documentation, passed to Converters
* @var string Character encoding of generated documentation, passed to Converters
* Stores parsed CHANGELOG/INSTALL/README files
* @var array Format: array(CHANGELOG => contents,
* Flag used to determine whether the last docblock
* was a page-level docblock.
var $_lastDocBlockWasPageLevel = false;
* Flag used to determine whether the Page-level
* DocBlock was declared in old or new style
var $_oldPageLevel = false;
* sets up basic data structures
* @param string Title of generated documentation, passed to Converters
* @see $title, $data, $classes, $proceduralpages
* Retrieve the relative path. If the path contains "pear/" it will
* be used as the base, otherwise the Program_Root string will be used.
* @global array uses 'Program_Root' option to replace it with '' for
* retrieving the source location of a file
* @param string path to file
function _getSourceLocation ($sl, $sourceloc)
global $_phpDocumentor_options;
if (empty ($sl)) return false;
* 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."
* @param string full path of file
* @param template-ready source location Program_Root/dir/file.php
* @global array uses the 'pear' option to determine whether to guess based
* @tutorial phpDocumentor.howto.pkg#using.command-line.pear
function _guessPackage ($path, $sourceloc)
if (isset ($_phpDocumentor_setting['pear']) && $_phpDocumentor_setting['pear'])
{ // can only have package and subpackage in this version
if (isset ($subpath[1 ])) $subpackage = $subpath[1 ];
return array ($package,$subpackage);
} else return array ($this->package, $this->subpackage);
} else return array ($this->package, $this->subpackage);
* handles post-parsing of include/require/include_once/require_once
* This function sets {@link $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
* {@link ProceduralPages} class
* @param integer $event Event number from {@link Parser.inc}
* @param parserInclude $data
if ($this->_lastDocBlockWasPageLevel)
if (!$this->_oldPageLevel)
$this->_lastDocBlockWasPageLevel = false;
// use the docblock template
// we don't have a docblock, create an empty one to get rid of errors
$this->last = new parserDocblock ();
// $this->last->setLineNumber($data->getLineNumber());
// addWarning(PDERROR_IGNORE_TAG_IGNORED,'include',$data->getName().'('.$data->getValue().')');
$this->last->overridePackage($this->category,$this->package,$this->subpackage,$data->getName (),'include');
$data->setDocBlock ($this->last);
* handles post-parsing of global variables
* This function sets {@link $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
* {@link ProceduralPages} class
* @param integer $event Event number from {@link Parser.inc}
* @param parserGlobal $data
if ($this->_lastDocBlockWasPageLevel)
if (!$this->_oldPageLevel)
$this->_lastDocBlockWasPageLevel = false;
// use the docblock template
// we don't have a docblock, create an empty one to get rid of errors
$this->last = new parserDocblock ();
// $this->last->setLineNumber($data->getLineNumber());
$this->last->overridePackage($this->category,$this->package,$this->subpackage,$data->getName (),'global');
$data->setDocBlock ($this->last);
if ($data->docblock ->getKeyword ('name'))
$a = $data->docblock ->getKeyword ('name');
* handles post-parsing of Package-level documentation pages.
* sets the {@link $package_pages}[$data->package] to $data
* @param integer $event Event number from {@link Parser.inc}
* @param parserPackagePage $data
* handle post-parsing of Tutorials.
* This adds the parsed tutorial to the tutorial tree
* @uses $tutorials sets the value of tutorials to parameter $data
* @param integer $event Event Number
* @param parserTutorial $data
$data->category = $GLOBALS['phpDocumentor_DefaultCategoryName'];
$this->tutorials[$data->package ][$data->subpackage ][$data->tutorial_type ][$data->name ] = $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
* @param integer $event Event number from {@link Parser.inc}
// use the docblock template
// we don't have a docblock, create an empty one to get rid of errors
$this->last = new parserDocblock ();
// $this->last->setLineNumber($data->getLineNumber());
$this->last->overridePackage($this->category,$this->package,$this->subpackage,$data->getName (),'var');
// addWarning(PDERROR_IGNORE_TAG_IGNORED,'var',$this->cur_class.'::'.$data->getName());
if (isset ($_phpDocumentor_setting['pear']) && $_phpDocumentor_setting['pear'])
$data->setDocBlock ($this->last);
$data->setDocBlock ($this->last);
* handles post-parsing of class constants
* This function aligns $data's
* $path var and packages to match the parent object
* @param integer $event Event number from {@link Parser.inc}
// use the docblock template
// we don't have a docblock, create an empty one to get rid of errors
$this->last = new parserDocblock ();
// $this->last->setLineNumber($data->getLineNumber());
$this->last->overridePackage($this->category,$this->package,$this->subpackage,$data->getName (),'const');
// addWarning(PDERROR_IGNORE_TAG_IGNORED,'var',$this->cur_class.'::'.$data->getName());
$data->setDocBlock ($this->last);
* 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
* Finally, it adds the method to the {@link Classes} class.
* @param integer $event Event number from {@link Parser.inc}
* @param parserMethod $data
// use the docblock template
// we don't have a docblock, create an empty one to get rid of errors
$this->last = new parserDocblock ();
// $this->last->setLineNumber($data->getLineNumber());
// addWarning(PDERROR_IGNORE_TAG_IGNORED,'method',$this->cur_class.'::'.$data->getName());
$this->last->overridePackage($this->category,$this->package,$this->subpackage,$data->getName (),'method');
foreach($data->listParams () as $key => $param)
$update_params[$key] = $param;
foreach($data->listGlobals () as $param)
$update_globals[] = $param[1 ];
foreach($data->listStatics () as $param)
$update_statics[] = $param[0 ];
if (isset ($update_params))
if (isset ($update_globals))
if (isset ($update_statics))
if ($data->getName () == $this->cur_class) $data->setConstructor ();
if ($data->getName () == '__construct') {
if ($data->getName () == '__destruct') {
if (isset ($_phpDocumentor_setting['pear']) && $_phpDocumentor_setting['pear'])
if (strpos($data->getName (), '_') === 0 && substr($data->getName (), 1 ) == $data->class )
if (strpos($data->getName (), '__') !== 0 ) {
$data->setDocBlock ($this->last);
$data->setDocBlock ($this->last);
* handles post-parsing of functions
* This function sets {@link $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
* {@link ProceduralPages} class
* @param integer $event Event number from {@link Parser.inc}
* @param parserFunction $data
if ($this->_lastDocBlockWasPageLevel)
if (!$this->_oldPageLevel)
$this->_lastDocBlockWasPageLevel = false;
// use the docblock template
// we don't have a docblock, create an empty one to get rid of errors
$this->last = new parserDocblock ();
// $this->last->setLineNumber($data->getLineNumber());
$this->last->overridePackage($this->category,$this->package,$this->subpackage,$data->getName (),'function');
foreach($data->listParams () as $key => $param)
$update_params[$key] = $param;
foreach($data->listGlobals () as $param)
$update_globals[] = $param[1 ];
foreach($data->listStatics () as $param)
$update_statics[] = $param[0 ];
if (isset ($update_params))
if (isset ($update_globals))
if (isset ($update_statics))
// if the function has no parameters, and 1 @param, add it to the list as optional, default value is description from @param
$data->addParam ($pars[0 ]['var'],$pars[0 ]['data']->getString ());
$data->setDocBlock ($this->last);
* handles post-parsing of defines
* This function sets {@link $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 {@link ProceduralPages} class
* @param integer $event Event number from {@link Parser.inc}
* @param parserDefine $data
if ($this->_lastDocBlockWasPageLevel)
if (!$this->_oldPageLevel)
$this->_lastDocBlockWasPageLevel = false;
// use the docblock template
// we don't have a docblock, create an empty one to get rid of errors
$this->last = new parserDocblock ();
// $this->last->setLineNumber($data->getLineNumber());
$this->last->overridePackage($this->category,$this->package,$this->subpackage,$data->getName (),'define');
$data->setDocBlock ($this->last);
* handles post-parsing of classes
* This function sets {@link $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 {@link $cur_class} to its
* name, and if an @ignore tag is found in the DocBlock, it sets
* {@link $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
* @param integer $event Event number from {@link Parser.inc}
* @param parserClass $data
if ($data->isInterface ())
$objectType = 'interface';
if ($this->_lastDocBlockWasPageLevel)
if (!$this->_oldPageLevel)
$doc->category = $this->category;
$doc->package = $this->package;
$doc->subpackage = $this->subpackage;
if (isset ($_phpDocumentor_setting['sourcecode']) &&
$_phpDocumentor_setting['sourcecode']) {
$this->_lastDocBlockWasPageLevel = false;
// use the docblock template
// we don't have a docblock, create an empty one to get rid of errors
$this->last = new parserDocblock ();
// $this->last->setLineNumber($data->getLineNumber());
$data->setDocBlock ($this->last);
* 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
* @param integer $event Event number from {@link Parser.inc}
* @param parserPage $data
$this->private_page = false;
$data->category = $this->category = $GLOBALS['phpDocumentor_DefaultCategoryName'];
$this->package = $GLOBALS['phpDocumentor_DefaultPackageName'];
$this->pages[$data->getPath ()] = $this->data;
* handles post-parsing of DocBlocks
* This function sets {@link $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:
* <li>First DocBlock in the file contains a @package tag</li>
* <li>First DocBlock in the file is immediately followed by another
* 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.
* <b>New</b> 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
* {@link _processPageLevelDocBlock}
* Finally, the function replaces the old parserPage in
* {@link parserData::$data}->parent with the new one containing information
* from the DocBlock by calling {@link addPage()}, and checks for
* @param integer $event Event number from {@link Parser.inc}
* @param parserDocBlock $data
if ($tdesc = $data->getKeyword ('desc'))
$data->setShortDesc ($tdesc);
unset ($data->tags ['desc']);
$this->_lastDocBlockWasPageLevel = false;
// 1st docblock in file, check for @package
if ($data->getExplicitPackage ())
// if the first docblock in a file
// contains a @package tag, then it is
$this->_processPageLevelDocBlock ($data);
$this->_lastDocBlockWasPageLevel = true;
$doc->category = $this->category;
$doc->package = $this->package;
$doc->subpackage = $this->subpackage;
// 2nd docblock in a row, and it's at the top of the file, page-level docblock
$this->_processPageLevelDocBlock ($this->last);
$this->_oldPageLevel = true;
$this->_lastDocBlockWasPageLevel = false;
* Process a Page-level DocBlock
* First, it checks for an @ignore tag,
* and if found, calls {@link ProceduralPages::ignorePage()}. An @ignore
* tag in a page-level DocBlock will ignore all functions, defines, global
* variables, and includes. It will not ignore classes! The function next
* checks for an @access private, and if --parseprivate is off, performs the
* same actions as @ignore.
* Next, it checks for the @name tag, which is used to rename the page.
* This is also a PEAR compatibility issue, and may not be very useful in
* the long run. Documentation is best when it refers to real entities in
* the package, and not to aliases.
function _processPageLevelDocBlock ($data)
// can only have 1 package-level docblock, others are ignored
if (isset ($_phpDocumentor_setting['sourcecode']) && $_phpDocumentor_setting['sourcecode'])
if (!$data->getExplicitPackage ())
list ($data->package ,$data->subpackage ) = $this->_guessPackage ($this->data->parent->getPath (), $this->data->parent->getSourceLocation ('dummy'));
$this->category = $this->data->parent->category = $data->category;
$this->subpackage = $this->data->parent->subpackage = $data->subpackage;
if ($data->getKeyword ('ignore'))
$this->private_page = true;
$this->package = $this->data->parent->package = $data->package;
$this->subpackage = $this->data->parent->subpackage = $data->subpackage;
if ($access = $data->getKeyword ('access'))
$this->private_page = true;
if ($data->getKeyword ('name'))
$a = $data->getKeyword ('name');
* Backward-compatibility only, use the new tutorials for more power
* @tutorial tutorials.pkg
* @param string package name of package file to parse
* @param string directory of file that contains package name
$pageParser->subscribe ('*',$this);
$pageParser->parse ($ret,false ,$package);
* called via {@link Parser::parse()} and Parser's inherited method
* {@link 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
* {@link $event_handlers} array and called to handle the $data
* @param integer $event event number from {@link Parser.inc}
* @param mixed $data if $event is {@link PHPDOCUMENTOR_EVENT_NEWSTATE}, $data is a {@link PHP_DOC_EVENT_END_PAGE} or {@link STATE_END_CLASS},
* otherwise $data is either a {@link parserDocBlock}, {@link parserPage} or descendant of {@link parserElement}
* @global array we use 'sourcecode' to determine whether to highlight the source
* of the current file if it has no file-level docblock
$this->packagecategories[$phpDocumentor_DefaultPackageName] = $phpDocumentor_DefaultCategoryName;
if (!$this->private_page)
if (isset ($_phpDocumentor_setting['sourcecode']) &&
$_phpDocumentor_setting['sourcecode'])
list ($doc->package ,$doc->subpackage ) = $this->_guessPackage ($this->data->parent->getPath (), $this->data->parent->getSourceLocation ('dummy'));
$this->private_page = false;
//echo $this->state_lookup[$data] . "\n";
$this->ric[$data[0 ]] = $data[1 ];
$this->_lastDocBlockWasPageLevel = false;
// 2nd docblock in a row, and it's at the top of the file, page-level docblock
// can only have 1 package-level docblock, others are ignored
$this->private_page = true;
$this->private_page = true;
$type = $data->getType ();
// fancy_debug($type,$data);
if (($type != 'page') && ($type != 'docblock') && ($type != 'packagepage') && ($type != 'tutorial'))
$this->$handle($event,$data);
* Replaces the {@link parserPage} represented by $this->pages[$path] with
* Called by {@link addPageIfNecessary(), handleDocBlock()} and
* {@link 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 {@link addPrivatePage()}. Otherwise, it sets the pages[$path] to
* be the parserPage $page and sets the package and subpackage to that of
* @param string full path to the file
$this->pages[$path]->setParent ($page);
if ($page->package != $GLOBALS['phpDocumentor_DefaultPackageName'])
if (!$this->pages[$path]->docblock )
$docblock->package = $page->package;
$docblock->subpackage = $page->subpackage;
$this->pages[$path]->docblock = $docblock;
$this->pages[$path]->docblock ->package = $page->package;
$this->pages[$path]->docblock ->subpackage = $page->subpackage;
* add a new {@link 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
* {@link $pages} array and then copies path information, and calls
* {@link addPage()} to set up packages
* @param string full path of page
if (!isset ($this->pages[$path]))
$this->pages[$path]->docblock ->package = $this->privatepages[$path]->docblock ->package;
$this->pages[$path]->docblock ->subpackage = $this->privatepages[$path]->docblock ->subpackage;
$this->pages[$path]->setParent ($par);
if (!empty ($_phpDocumentor_setting['packageoutput']))
$packages = explode(',',$_phpDocumentor_setting['packageoutput']);
if (!empty ($_phpDocumentor_setting['packageoutput']) &&
$this->pages[$path]->parent ->package != $class->docblock ->package &&
$this->pages[$path]->parent ->package = $class->docblock ->package;
* Adds a {@link parserPage} element to the {@link parserData} element in
* $this->privatepages[$path]
* Performs a similar function to addPage, but adds to the
* {@link $privatePages} array
* @param parserPage $page
* @param string $path full path to the page
* if privatepages is still empty,
* we need to initialize it with an empty
* path=>ParserData element, so that it has
* a top-level element... otherwise the setParent() call
if (isset ($page->package ) && $page->package != $GLOBALS['phpDocumentor_DefaultPackageName'])
$docblock->package = $page->package;
$docblock->subpackage = $page->subpackage;
$this->privatepages[$path]->docblock ->package = $page->package;
$this->privatepages[$path]->docblock ->subpackage = $page->subpackage;
* adds a processed descendant of {@link parserElement} to the {@link $pages}
* array or {@link $privatepages} array
* This function expects the page to exist in either $pages or $privatepages. It calls the
* {@link parserData::addElement()} method to add $element to the page.
* @param parserElement $element this will actually be a descendant of parserElement
if (isset ($this->pages[$path]))
if ($element->type == 'class' || $element->type == 'method'
|| $element->type == 'var' || $element->type == 'const')
$this->pages[$path]->addElement ($element);
if (isset ($this->pages[$path]))
$this->pages[$path]->addElement ($element);
* Add all the @uses tags from $element to the $uses array so that @usedby
* virtual tags can be added
* @uses parserUsesTag::getSeeElement() used to initialize {@link $uses}
* @uses parserUsesTag::getDescription() used to initialize {@link $uses}
* @param parserElement descendant of parserElement
* @param string full path to the file
if (isset ($element->type ) && $element->type == 'page')
$element = $this->pages[$element->path ];
if (!$this->parsePrivate && isset ($element->docblock ->hasaccess ) && $element->docblock ->hasaccess )
$a = $element->docblock ->getKeyword ('access');
if (is_object($a) && $a->getString () == 'private') return;
if (isset ($this->pages[$path]))
$uses = $element->docblock ->getKeyword ('uses');
if (!is_array($uses)) $uses = array ($uses);
$el = $use->getSeeElement ();
$description = $use->getDescription ();
$this->uses[$el][] = array ($element, $description);
if (isset ($this->pages[$path]))
$uses = $element->docblock ->getKeyword ('uses');
if (!is_array($uses)) $uses = array ($uses);
$el = $use->getSeeElement ();
$description = $use->getDescription ();
$this->uses[$el][] = array ($element, $description);
* Add a {@link parserUsedByTag} link to every element referred to by @uses
* @param Converter temporary converter used to retrieve abstract links
* @uses phpDocumentor_IntermediateParser::addUses() indirectly, as
* addUses() sets up $uses, which is iterated over here
* @uses $pages sets up all @usedby tags from here
function _setupUsesList (&$converter)
$converter->_createPkgElements ($this->pages);
foreach($this->uses as $link => $elements)
foreach($elements as $element)
if ($element[0 ]->type == 'method' || $element[0 ]->type == 'var' ||
$element[0 ]->type == 'const')
$converter->class = $element[0 ]->getClass ();
if ($element[0 ]->type == 'class')
$converter->class = $element[0 ]->getName ();
$reallink = $converter->getLink ($link,$element[0 ]->docblock ->package );
// add a used by tag to the docblock of the destination
$this->pages[$reallink->path ]->docblock ->addUsedBy (
$element[0 ]->getLink ($converter, false , true ),
if (isset ($this->pages[$reallink->path ]))
$i< count($this->pages[$reallink->path ]->elements );
if ($this->pages[$reallink->path ]->elements [$i]->type ==
$this->pages[$reallink->path ]->
$this->pages[$reallink->path ]->elements [$i]->
$element[0 ]->getLink ($converter,false ,true ),
// debug('added @usedby to '.str_replace('link','',phpDocumentor_get_class($reallink)).' '.$reallink->name);
if (isset ($this->pages[$reallink->path ]))
for ($i=0; $i< count($this->pages[$reallink->path ]->classelements ); $i++ )
if ($this->pages[$reallink->path ]->classelements [$i]->type ==
$this->pages[$reallink->path ]->classelements [$i]->getName () == $reallink->name &&
(!isset ($reallink->class ) ||
$this->pages[$reallink->path ]->classelements [$i]->getClass () == $reallink->class ))
$this->pages[$reallink->path ]->classelements [$i]->docblock ->addUsedBy ($element[0 ]->getLink ($converter,false ,true ), $element[1 ]);
// debug('added @usedby to '.str_replace('link','',phpDocumentor_get_class($reallink)).' '.$reallink->name);
* Interface to the Converter
* This function simply passes {@link $pages} and {@link 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
* @uses Converter::walk() passes {@link $pages} and {@link $package_pages}
* @uses Converter::Output()
function Convert($title, $converter)
$converter->Output ($title);
* @uses Classes::Inherit() passes $this
* Clean up Procedural Pages
* @uses ProceduralPages::setupPages() passes $this
* If the parent class of $class is in a different package, adds it to the
* {@link $package_parents} array
* @param parserClass &$class
if ($class->docblock ->package == $par->docblock ->package ) return;
$this->package_parents[$class->docblock ->package ] = $par->docblock ->package;
* Add a converter name to use to the list of converters
* Sets up the {@link $converters} array.
* First, the Converter's file is included, and then, if successful,
* the converter classname is tested for existance. If all is good,
* then the templates are added to the list of converters/templates to use}}}
* @param string $output output format (HTML, PDF, XML). Must be all caps
* @param string $name Converter name (frames, for example, is the name of
* @param string $template template to use, should be a relative path to the
* templates dir (like DOM/default)
if ('@PEAR-DIR@' != '@'. 'PEAR-DIR@') {
$templateBase = 'PhpDocumentor/phpDocumentor/Converters';
$templateBase = str_replace('\\','/',$GLOBALS['_phpDocumentor_install_dir']) . '/phpDocumentor/Converters';
// include the parent template
$filename = $templateBase . '/' . $output . '/' . $parent . '/' . $output
. $parent . 'Converter.inc';
$filename = $templateBase .
* does a natural case sort on two {@link parserElement} descendants
* @see generateElementIndex()
* does a natural case sort on two class elements (either
* {@link parserClass, parserMethod} or {@link parserVar}
* @see generateElementIndex()
if ($a->isConstructor ) return -1;
if ($b->isConstructor ) return 1;
if ($a->isDestructor ) return -1;
if ($b->isDestructor ) return 1;
* 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 {@link ProceduralPages::setupPages()}
* and {@link Classes::Inherit()}. Then, it sorts elements of the $pages
* array and calls Convert for each Converter in the $converters array
function Output ($title = "Generated Documentation")
$GLOBALS['phpDocumentor_errors']->curfile = false;
// var_dump($this->uses);
foreach($this->pages as $i => $page)
usort($this->pages[$i]->elements ,array ($this,'elementCmp'));
usort($this->pages[$i]->classelements ,array ($this,'ClasselementCmp'));
$a = new __dummyConverter ($this->all_packages, $this->package_parents, $this->classes, $this->proceduralpages, $this->packageoutput, $this->parsePrivate, $this->quietMode, $this->targetDir , '', $this->title, $this->charset);
$this->_setupUsesList ($a);
foreach($blah as $converter => $templates)
foreach($templates as $template)
if (count($templates) > 1 )
$a = new $converter($this->all_packages, $this->package_parents, $this->classes, $this->proceduralpages, $this->packageoutput, $this->parsePrivate, $this->quietMode, $this->targetDir . $extraout, $template, $this->title, $this->charset);
if (isset ($this->tutorials)) $a->setTutorials ($this->tutorials);
* Sets the output directory
* @param string $dir the output directory
* Sets the template base directory
* @param string $dir the template base directory
* @tutorial phpDocumentor.howto.pkg#using.command-line.templatebase
* 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.
* show warnings for undocumented elements
* If set to false, no warnings will be shown for undocumented elements.
* Useful for identifying classes and methods that haven't yet been documented.
* @param bool $undocumentedElementWarnings
* set display of elements marked with @access private
* If set to true, elements will be displayed
function pagesort ($a, $b)
Documentation generated on Mon, 11 Mar 2019 15:50:29 -0400 by phpDocumentor 1.4.4. PEAR Logo Copyright © PHP Group 2004.
|