Source for file DocBlockTags.inc
Documentation is available at DocBlockTags.inc
* All abstract representations of DocBlock tags are defined
* by the classes in this file
* phpDocumentor :: automatic documentation generator
* Copyright (c) 2002-2008 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
* @category ToolsAndUtilities
* @subpackage DocBlockTags
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version CVS: $Id: DocBlockTags.inc 287889 2009-08-30 07:27:39Z ashnazg $
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @see parserDocBlock, parserInclude, parserPage, parserClass
* @see parserDefine, parserFunction, parserMethod, parserVar
* @since separate file since version 1.2
* @todo CS cleanup - change package to PhpDocumentor
* used to represent standard tags like @access, etc.
* This class is aware of inline tags, and will automatically handle them
* using inherited functions
* @category ToolsAndUtilities
* @subpackage DocBlockTags
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version Release: @VER@
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @todo CS cleanup - change package to PhpDocumentor
* @todo CS cleanup - change classname to PhpDocumentor_*
* Type is used by many functions to skip the hassle of
* if phpDocumentor_get_class($blah) == 'parserBlah' always '_tag'
* tag name (see, access, etc.)
* @param string $keyword tag name
* @param parserStringWithInlineTags $value tag value
* @param boolean $noparse whether to parse the $value
function parserTag($keyword, $value, $noparse =
false)
$parser->subscribe('*', $this);
$parser->parse($value->value, true, 'parserstringwithinlinetags');
* Perform the output conversion on this {@link parserTag}
* using the {@link Converter output converter} that is passed in
* @param Converter &$converter the converter object
* @todo CS cleanup - rename to convert for camelCase rule
$a =
$val->Convert($converter);
foreach ($this->value as $val) {
// this is only true if we processed the description
==
'parserstringwithinlinetags') {
EncloseParagraph($val->Convert($converter));
$result .=
$val->Convert($converter);
$a =
$this->value->Convert($converter);
* Gets a count of the number of paragraphs in this
* Useful in determining whether to enclose the
* tag in a paragraph or not.
* @return integer (actually, body is empty, so it doesn't return at all)
* @todo does this need to be implemented? its body is empty
function _valueParagraphCount()
* Called by the {@link parserDescParser} when processing a description.
* @param integer $a not used
* @param array $desc array of {@link parserStringWithInlineTags}
* representing paragraphs in the tag description
* @see parserTag::parserTag()
* @todo CS cleanup - rename to handleEvent for camelCase rule
* Returns the text minus any inline tags
* @return string the text minus any inline tags
* @see parserStringWithInlineTags::getString()
foreach ($this->value as $val) {
$result .=
$val->getString();
return $this->value->getString();
* This class represents the @name tag
* @category ToolsAndUtilities
* @subpackage DocBlockTags
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version Release: @VER@
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @tutorial tags.name.pkg
* @todo CS cleanup - change package to PhpDocumentor
* @todo CS cleanup - change classname to PhpDocumentor_*
* @param string $name tag name (not used)
* @param string $value tag value
* process this tag through the given output converter
* @param Converter &$c output converter
* @return string converted value of the tag
* @see parserStringWithInlineTags::Convert()
* @todo CS cleanup - rename to convert for camelCase rule
* This class represents the @access tag
* @category ToolsAndUtilities
* @subpackage DocBlockTags
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version Release: @VER@
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @tutorial tags.access.pkg
* @todo CS cleanup - change package to PhpDocumentor
* @todo CS cleanup - change classname to PhpDocumentor_*
* set to true if the returned tag has a value type of private, protected
* or public, false otherwise
* checks $value to make sure it is private, protected or public, otherwise
* it's not a valid @access tag
* @param parserStringWithInlineTags $value the tag value
$value =
$value->getString();
* process this tag through the given output converter
* @param Converter &$converter the output converter
* @return string converted value of the tag
* @see parserStringWithInlineTags::Convert()
* @todo CS cleanup - rename to convert for camelCase rule
* No inline tags are possible, returns 'public', 'protected' or 'private'
* @return string returns the text minus any inline tags
* represents the "@return" tag
* @category ToolsAndUtilities
* @subpackage DocBlockTags
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version Release: @VER@
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @tutorial tags.return.pkg
* @todo CS cleanup - change package to PhpDocumentor
* @todo CS cleanup - change classname to PhpDocumentor_*
* the type a function returns
* contains a link to the documentation for a class
* passed as a type in @return, @var or @param
* /** @return myclass blahblahblah
* In this case, $converted_returnType will contain a link to myclass
* instead of the string 'myclass'
* @var mixed either the same as $returnType or a link to the docs for a class
* @param string $returnType returned datatype
* @param parserStringWithInlineTags $value tag value
* process this tag through the given output converter
* (sets up the $converted_returnType)
* @param Converter &$converter the output converter
* @return string converted value of the tag
* @see parserStringWithInlineTags::Convert(), $converted_returnType
* @todo CS cleanup - rename to convert for camelCase rule
foreach ($types as $returntype) {
$a =
$converter->getLink($returntype);
$my_types .=
$converter->
returnSee($a, $converter->type_adjust($returntype));
$my_types .=
$converter->type_adjust($returntype);
returnSee($a, $converter->type_adjust($this->returnType));
* represents the "@property" tag
* @category ToolsAndUtilities
* @subpackage DocBlockTags
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version Release: @VER@
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @tutorial tags.property.pkg
* @todo CS cleanup - change package to PhpDocumentor
* @todo CS cleanup - change classname to PhpDocumentor_*
* the type a property has
* set up the property tag
* @param string $returnType the tag value's datatype
* @param parserStringWithInlineTags $value the tag value
parent::parserTag($this->keyword, $value);
* represents the "@property-read" tag
* @category ToolsAndUtilities
* @subpackage DocBlockTags
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version Release: @VER@
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @tutorial tags.property.pkg
* @todo CS cleanup - change package to PhpDocumentor
* @todo CS cleanup - change classname to PhpDocumentor_*
* represents the "@property-write" tag
* @category ToolsAndUtilities
* @subpackage DocBlockTags
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version Release: @VER@
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @tutorial tags.property.pkg
* @todo CS cleanup - change package to PhpDocumentor
* @todo CS cleanup - change classname to PhpDocumentor_*
* always 'property-write'
* represents the "@method" tag
* @category ToolsAndUtilities
* @subpackage DocBlockTags
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version Release: @VER@
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @tutorial tags.method.pkg
* @todo CS cleanup - change package to PhpDocumentor
* @todo CS cleanup - change classname to PhpDocumentor_*
* the return type a method has
* represents the "@var" tag
* @category ToolsAndUtilities
* @subpackage DocBlockTags
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version Release: @VER@
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @todo CS cleanup - change package to PhpDocumentor
* @todo CS cleanup - change classname to PhpDocumentor_*
* represents the "@param" tag
* @category ToolsAndUtilities
* @subpackage DocBlockTags
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version Release: @VER@
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @tutorial tags.param.pkg
* @todo CS cleanup - change package to PhpDocumentor
* @todo CS cleanup - change classname to PhpDocumentor_*
* represents the "@staticvar" tag
* @category ToolsAndUtilities
* @subpackage DocBlockTags
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version Release: @VER@
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @tutorial tags.staticvar.pkg
* @todo CS cleanup - change package to PhpDocumentor
* @todo CS cleanup - change classname to PhpDocumentor_*
* represents the "@link" tag
* @category ToolsAndUtilities
* @subpackage DocBlockTags
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version Release: @VER@
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @tutorial tags.link.pkg
* @todo CS cleanup - change package to PhpDocumentor
* @todo CS cleanup - change classname to PhpDocumentor_*
* @param string $link URL to link to
* (might also contain the URL's
$start =
$val =
$link->getString();
* represents the "@see" tag
* @category ToolsAndUtilities
* @subpackage DocBlockTags
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version Release: @VER@
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @todo CS cleanup - change package to PhpDocumentor
* @todo CS cleanup - change classname to PhpDocumentor_*
* @param string $name element to link to
* process this tag through the given output converter
* @param Converter &$converter the output converter
* @return string converted value of the tag
* @see parserStringWithInlineTags::Convert()
* @todo CS cleanup - rename to convert for camelCase rule
if ($this->value->hasInlineTag()) {
$a =
$converter->getLink(trim($this->value->Convert($converter)));
return $converter->returnLink($a, str_replace('PHP_MANUAL#', '',
$this->value->Convert($converter)));
return $converter->returnSee($a);
// getLink parsed a comma-delimited list of linked thingies,
// add the commas back in
foreach ($a as $i =>
$bub) {
$b .=
$converter->returnSee($a[$i]);
* represents the "@see" tag
* Link to a license, instead of including lines and lines of license information
* @category ToolsAndUtilities
* @subpackage DocBlockTags
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version Release: @VER@
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @tutorial tags.license.pkg
* @todo CS cleanup - change package to PhpDocumentor
* @todo CS cleanup - change classname to PhpDocumentor_*
* @param string $name unused?
* @param string $link URL to link to
$a =
explode(' ', $link->getString());
$license =
join($a, ' ');
* represents the "@uses" tag
* This is exactly like @see except that the element used
* has a @useby link to this element added to its docblock
* @category ToolsAndUtilities
* @subpackage DocBlockTags
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version Release: @VER@
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @tutorial tags.uses.pkg
* @todo CS cleanup - change package to PhpDocumentor
* @todo CS cleanup - change classname to PhpDocumentor_*
* @param string $seeel element to link to
* @param parserStringWithInlineTags $description description of how
if ($seeel->hasInlineTag()) {
$this->_description =
$description;
* Return a link to documentation for other element,
* and description of how it is used
* Works exactly like {@link parent::Convert()}
* except that it also includes a description of
* how the element used is used.
* @param Converter &$c the output converter
* @return string link to the uses target
* @todo CS cleanup - rename to convert for camelCase rule
$this->value =
$this->_description;
* Get the text of the link to the element that is being used
return $this->value->getString();
* Get the description of how the element used is being used.
* @return parserStringWithInlineTags
return $this->_description;
* This is a virtual tag, it is created by @uses to cross-reference the used element
* This is exactly like @uses.
* @category ToolsAndUtilities
* @subpackage DocBlockTags
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version Release: @VER@
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @todo CS cleanup - change package to PhpDocumentor
* @todo CS cleanup - change classname to PhpDocumentor_*
* @param abstractLink $link link of element that uses this element
* @param string $description description of how the element is used
$this->value =
$description;
* process this tag through the given output converter
* @param Converter &$c the output converter
* @todo CS cleanup - rename to convert for camelCase rule
$see =
$c->returnSee($this->_link);
* This is exactly like @see except that it only links to tutorials
* @category ToolsAndUtilities
* @subpackage DocBlockTags
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version Release: @VER@
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @tutorial phpDocumentor/tutorials.pkg
* @tutorial tags.tutorial.pkg
* @todo CS cleanup - change package to PhpDocumentor
* @todo CS cleanup - change classname to PhpDocumentor_*
* process this tag through the given output converter
* @param Converter &$converter the output converter
* @see parserStringWithInlineTags::Convert()
* @todo CS cleanup - rename to convert for camelCase rule
$a =
$converter->getTutorialLink(trim($this->value->Convert($converter)));
return $converter->returnSee($a);
// getLink parsed a comma-delimited list of linked thingies,
// add the commas back in
foreach ($a as $i =>
$bub) {
$b .=
$converter->returnSee($a[$i]);
* represents "@filesource"
* Use this to create a link to a highlighted phpxref-style source file listing
* @category ToolsAndUtilities
* @subpackage DocBlockTags
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version Release: @VER@
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @tutorial tags.filesource.pkg
* @todo CS cleanup - change package to PhpDocumentor
* @todo CS cleanup - change classname to PhpDocumentor_*
* Flag variable, controls double writes of file for each converter
var $_converted =
array();
* Set {@link $source} to $value, and set up path
* @param string $filepath the file's path
* @param array $value output from
* {@link phpDocumentorTWordParser::getFileSource()}
* Return a link to the highlighted source and generate the source
* @param Converter &$c the output converter
* @return string output from {@link getSourceLink()}
* @uses ConvertSource() generate source code and write it out
* @todo CS cleanup - rename to convert for camelCase rule
* convert the source code
* @param Converter &$c the output converter
* @uses phpDocumentor_HighlightParser highlights source code
* @todo CS cleanup - rename to convertSource for camelCase rule
* @todo what's up with all the "return" statements?
* can they _all_ be removed?
ProgramExample($this->source, true, false, false, false, $this->path));
parse($this->source, $c, false, false, false, $this->path);
* have the output converter write the source code
* @param Converter &$c the output converter
* @param string $source highlighted source code
* @uses Converter::writeSource() export highlighted file source
$c->writeSource($this->path, $source);
* gets path to the sourcecode file
* @param Converter &$c the output converter
* @return output from getSourceLink()
* @uses Converter::getSourceLink()
return $c->getSourceLink($this->path);
* @category ToolsAndUtilities
* @subpackage DocBlockTags
* @copyright 2002-2008 Gregory Beaver
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL
* @version Release: @VER@
* @link http://www.phpdoc.org
* @link http://pear.php.net/PhpDocumentor
* @tutorial tags.example.pkg
* @todo CS cleanup - change package to PhpDocumentor
* @todo CS cleanup - change classname to PhpDocumentor_*
* Reads and parses the example file indicated
* The example tag takes one parameter: the full path to a php file that
* should be parsed and included as an example.
* @param parserStringWithInlineTags $value tag value
* @param string $current_path path of file containing
* @uses phpDocumentorTWordParser::getFileSource() uses to parse an example
* and retrieve all tokens by line number
* @todo does this "x = y = z = false" still work as expected in PHP5?
* @todo CS cleanup - rename constant to TOKENIZER_EXT
parent::parserTag('example', $value);
// code thanks to Sam Blum, modified by Greg Beaver
$tagValue =
$value->getString();
// make sure the format is stuff.ext description
if (!preg_match('`(.*)\.(\w*)\s(.*)`', $tagValue, $match)) {
// or format is stuff.ext
if (!preg_match('`(.*)\.(\w*)\s*$`', $tagValue, $match)) {
// Murphy: Some funny path was given
$original_path =
$tagValue; // used for error output
if (strlen($match[1]) ===
0) {
// Murphy: Some funny path was given
$original_path =
$tagValue; // used for error output
$title =
trim($match[3]);
// Replace windows '\' the path.
// Is there a path and a file or is it just a file?
if (strpos($pathTmp, '/') ===
false) {
$fileName =
$pathTmp .
'.'.
$fileExt;
// split the path on the last directory, find the filename
$splitPos =
strrpos($pathTmp, '/');
$pathOnly =
substr($match[1], 0, $splitPos+
1);
$fileName =
substr($match[1], $splitPos+
1) .
'.'.
$fileExt;
// Is the path absolute? (i.e. does it start like an absolute path?)
if (('/' ===
$pathTmp[0]) ||
preg_match('`^\w*:`i', $pathTmp)) {
// works for both windows 'C:' and URLs like 'http://'
$isAbsPath =
true; // Yes
$original_path =
$pathOnly .
$fileName;
// Now look for the file starting with abs. path.
// remove any weirdities like /../file.ext
// Alway break if abs. path was detected,
// even if file was not found.
// Search for the example file some standard places
// 1) Look if the ini-var examplesdir is set and look there ...
if (isset
($_phpDocumentor_setting['examplesdir'])) {
$tmp =
realpath($_phpDocumentor_setting['examplesdir']
$path =
$tmp; // Yo! found it :)
// 2) Then try to look for an 'example/'-dir
// below the *currently* parsed file ...
if (!empty($current_path)) {
$path =
$tmp; // Yo! found it :)
// 3) Then try to look for the example file
// below the subdir PHPDOCUMENTOR_BASE/examples/ ...
$path =
$tmp; // Yo! found it :)
$path =
$tmp; // Yo! found it :)
// If we reach this point, nothing was found and $path is false.
$this->_title =
'example not found';
$this->_title =
($title) ?
$title :
'example';
// make a unique html-filename but avoid it to get too long.
DIRECTORY_SEPARATOR, '/'), array('_', '_', '_'), $path);
$uniqueFileName =
substr($uniqueFileName, -
50) .
'_' .
md5($path);
$this->path =
$uniqueFileName;
$this->source =
$obj->getFileSource();
$this->origsource =
$example;
* convert the source code
* @param Converter &$c the output converter
* @uses phpDocumentor_HighlightParser highlights source code
* @todo CS cleanup - rename to convertSource for camelCase rule
* @todo what's up with all the "return" statements?
* can they _all_ be removed?
null, null, null, $this->origsource));
$return =
$parser->parse($this->source, $c);
* have the output converter write the source code
* @param Converter &$c the output converter
* @param string $source highlighted source code
* @uses Converter::writeExample() writes final example out
$c->writeExample($this->_title, $this->path, $source);
* Retrieve a converter-specific link to the example
* @param Converter &$c the output converter
* @uses Converter::getExampleLink() retrieve the link to the example
if (!$this->path) return $this->_title;
return $c->getExampleLink($this->path, $this->_title);