Primary phpDocumentor Documentation
phpDocumentor HOWTO written by Gregory Beaver and Joshua Eichorn
Copyright © 2002, Gregory Beaver, Joshua Eichorn
Introduction
Basics
DocBlock Tags
Inline Tags
Documentable PHP elements
A Simple Example
phpDocumentor command-line switches
phpDocumentor web interface notes
phpDocumentor is the most advanced automatic documentation system written for PHP, in PHP. This package has many features:
Note: if this howto looks bad, get a browser that supports css
The documentation process begins with the most basic element of phpDocumentor: a Documentation block or DocBlock. A basic DocBlock looks like this:
/**
*
*/
A DocBlock is an extended C++-style PHP comment that begins with "/**" and has an "*" at the beginning of every line. NOTE: Any line within a DocBlock that doesn't begin with a * will be ignored. DocBlocks precede the element they are documenting. To document function "foo()", type:
/**
* Defies imagination, extends boundaries and saves the world ...all before breakfast!
*/
function foo()
{
}
define() statements, functions, classes, class methods, and class vars can all be documented.
A DocBlock contains three basic segments in this order:
The Short Description starts on the first line, and can be terminated with a blank line or a period. A period inside a word (like example.com or 0.1 %) is ignored. If the Short Description would become more than three lines long, only the first line is taken. The Long Description continues for as many lines as desired and may contain html markup for display formatting. Here is a sample DocBlock with a Short and a Long Description:
/**
* return the date of Easter
*
* Using the formula from "Formulas that are way too complicated for anyone to
* ever understand except for me" by Irwin Nerdy, this function calculates the
* date of Easter given a date in the Ancient Mayan Calendar, if you can also
* guess the birthday of the author.
*/
Tags are single words prefixed by a "@" symbol. Tags inform phpDocumentor how to present information and modify display of documentation. All tags are optional, but if you use a tag, they do have specific requirements to parse properly.
More tags may be added in the future, not all tags are implemented at this time in phpdocumentor, however they are all recognized as tags and will at least be displayed
/**
* The short description
*
* As many lines of extendend description as you want {@link element} links to an element
* {@link http://www.example.com Example hyperlink inline link} links to a website. The inline
* source tag displays function source code in the description:
* {@source}
* Below this goes the tags to further describe element you are documenting
*
* @param type $varname description
* @return type description
* @access public or private
* @author author name <author@email>
* @copyright name date
* @version version
* @see name of another element that can be documented, produces a link to it in the documentation
* @link a url
* @since a version or a date
* @deprecated description
* @deprec alias for deprecated
* @global type $globalvarname
or
* @global type description of global variable usage in a function
* @staticvar type description of static variable usage in a function
* @name procpagealias
or
* @name $globalvaralias
* @magic phpdoc.de compatibility
* @todo phpdoc.de compatibility
* @exception Javadoc-compatible, use as needed
* @throws Javadoc-compatible, use as needed
* @var type a data type for a class variable
* @package package name
* @subpackage sub package name, groupings inside of a project
*/
function if_there_is_an_inline_source_tag_this_must_be_a_function()
{
...
}
Tag Information:
type is the type of the global variable. $globalvarname is the EXACT name of the global variable as it is defined in the source code. Use this tag sytanx to document global variable definitions/** * @global string $GLOBALS['mystring'] */ $GLOBALS['mystring'] = "this is my string";
type is the type of the global variable. Use this tag syntax to document the declaration of global variables used in functions and declared with global keyword./** * @param string $param what is added to the global variable * @global string parameter is added to it */ function myfunction($param) { global $mystring; }
type is the type of the static variable. Use this tag syntax to document the declaration of static variables used in functions./** * @param string $param what is added to the global variable * @staticvar string parameter is added to it */ function myfunction($param) { static $mystring = 'hello'; }
$globalalias is the name you'd like displayed for documentation. This tag should be used to display a simpler version of a global variable. It will also make it more likely that the function version of @global will link to the global variable's documentation properly./** * now the @global declaration for function myfunction can find this variable * @global string $GLOBALS['mystring'] * @name $mystring */ $GLOBALS['mystring'] = "this is my string";
procpagealias is the name you'd like to use for a procedural page instead of its file.ext. Note that using this tag break auto-linking from include("file.ext") where the procedural page's filename is file.ext
type is the type of a class variable. @var grabs the first word only, the rest is shunted to description. Default type is "mixed" if not included. Use this tag to document variables with type restrictions.
type is the type of a value returned from a method or function.
description a brief description of the value returned
use this tag in a DocBlock preceding a function or method./** * return the day of the week * * @param string $month 3-letter Month abbreviation * @param integer $day day of the month * @param integer $year year * @return integer 0 = Sunday, value returned is from 0 (Sunday) to 6 (Saturday) */ function day_week($month, $day, $year) { ... }
type is the type of parameter$varname, which may be one of: (string, array, integer, double, class, mixed)the @param tag can refer to more parameters than the function lists, to allow documenting of functions that use func_get_args
$varname is the name of the parameter, and must be preceded by the $ punctuator
description a brief description of this parameter, which may be more than one line
element may be the name of any documented element (procedural page, constant, function, class, class method, class variable). phpDocumentor recognizes the element type based on the presence of punctuators:If elements are separated by commas, phpDocumentor will parse each element and return them as a list (time-saver). To resolve name conflicts resulting from class inheritance, use the :: scope operator classname::method() or classname::$variable.
- $element is a class variable in the current class - the class that contains the DocBlock
- element() is either a method in the current class or a function in the current file
- element is either the name of a constant or of a class
- file.ext is a procedural page's filename
/** * class 1 * * example of {@link http://phpdocu.sourceforge.net Inline linking to a website} * example of use of the :: scope operator * @see subclass::method() */ class main_class { /** * example of linking to same class, outputs "function main_class::parent_method() * @see function parent_method */ var $foo = 3; /** * example of comma-separated @see and of linking to a procedural page "funcs.php" * @see $foo, funcs.php */ var $bar = array('15'); /** * subclass inherits this method. * example of a word which is either a constant or class name, in this case a classname * @see subclass * @see subclass::$foo */ function parent_method() { if ($this->foo==9) die; } } /** * this class extends main_class * @see main_class */ subclass extends main_class { /** * bar. * example of same class lookup - see will look through parent hierarchy to find the method in {@link main_class} * the above inline link tag will parse as main_class * @see parent_method() */ var $foo = 9; }
@package is used to group documented elements together. If @package is not included, elements are grouped in the "default" package. The name of the default package can be changed using command-line switch -dn or --defaultpackagename. A package name must be one word containing only letters, numbers and [, ], - or _, allowing output of directories by package name to work. The parser will exit on an illegal package name.
There are two kinds of @package tags: class-level and page-level. For version 1.0, the parser uses certain rules to determine whether a @package tag applies to a procedural page or to a class.
@package should be used to help you logically group related elements. You write classes to group related functions and data together, and phpDocumentor represents the contents of files (functions, defines, and includes) as "Procedural Pages." A package is used to group classes and procedural pages together in the same manner that a directory groups related files together.
Page-level @package
Page-level @package must be in a page-level DocBlock. The first DocBlock in a file is a page-level DocBlock IF AND ONLY IF it is immediately followed by another DocBlock. Here is a page-level DocBlock followed by a class DocBlock:Note that the 2nd DocBlock may document any element, such as:/** * this page-level DocBlock is used to describe all of the functions, includes, and defines in this file * @package pagepackage */ /** * this class-level DocBlock is used to describe all of the methods and vars in this class */ class foo { ... }
Class-level @package/** * this page-level DocBlock is used to describe all of the functions, includes, and defines in this file * @package pagepackage */ /** * this DocBlock describes the include that follows */ include('file.ext');
Class-level @package must be in a DocBlock preceding a class definition.
@subpackage is used to group classes and functions into sub-sections of the main package, and has the same naming conventions as @package
- a @see-style element is described above, and may be the name of a class, function, variable, or constant
- any valid URL (uniform resource locator) will be output as this html: <a> tag as <a href="URL">optional description of URL<\a>
valid URLS include websites (http://www.example.com), ftp sites (ftp://ftp.example.com), telnet sites (telnet://example.com), etc./** * class 1 * * example of {@link http://phpdocu.sourceforge.net} * displays as "example of http://phpdocu.sourceforge.net" */ class main_class { /** * This function sends the user to {@link http://www.sf.net The SourceForge Website} * displays as "This function send the user to The SourceForge Website" */ function goto_sourceforge() { header("Location: http://www.sf.net"); } } /** * this class extends {@link main_class} * displays as "this class extends main_class" */ subclass extends main_class { /** * bar. * this class inherits {@link main_class::goto_sourceforge()} */ var $foo = 9; }
Displays highlighted source code of a function. {@source} will be ignored anywhere but in the long description of a function. {@source} has two optional parameters:
- a starting line number to parse
- an ending line number to parse. If the starting line number is present, {@source} will display the source code of the function from the starting line number to the end of the function. If the ending line number is present, {@source} will display an excerpt of the function code beginning on the first line number, and ending on the second.
Every major reusable element in PHP can be documented:
Packages are used to help you logically group related elements. You write classes to group related functions and data together, and phpDocumentor represents the contents of files (functions, defines, and includes) as "Procedural Pages." A package is used to group classes and procedural pages together in the same manner that a directory groups related files together. A Package-level doc is an html file that documents general things about an entire package. It has the name "package.html" where package is the name of the package. In other words, for package foo that contains class bar in file /php/bar.php, phpDocumentor will attempt to document "foo.html" by looking for /php/foo.html. Package-level docs should be in the same directory as any file that contains a page-level or class-level @package tag
Package-level docs should be in standard html format. The only valid tags in Package-level documentation are inline tags. For this release, that means ONLY {@link} may be used in package-level documentation
Here is some example package-level documentation for package baz that contains classes fooclass and barclass
<html>
<head>
<title>Package baz</title>
</head>
<body>
This package is essential. using class {@link fooclass} you can instruct your computer to brush your teeth for you.
Combining this functionality with the back massage given by {@link barclass}, you may truly retire in comfort.
In particular, {@link barclass::footmassage()} is a most exquisite experience.
Please follow this list of links for more help:
<ul>
<li><a href="http://www.microsoft.com/support"><The reinstall Windows hotline>
<li><a href="http://www.php.net"><Heaven>
<li><a href="http://phpdocu.sourceforge.net"><The phpDocumentor Homepage>
<li><a href="http://www.chiaraquartet.net"><The most beautiful music you've ever heard>
</ul>
</body>
</html>
Procedural Pages are any physical files that phpDocumentor documents. They may contain any documentable element, or nothing at all, but should contain at least a page-level DocBlock to be of any use for the end-user. phpDocumentor documents all includes, defines, and functions found in the file, and links to documentation for classes defined in the file, but every class is documented separately from the physical file that contains it. In other words, if foo.php contains function bar() and class baz, bar will be documented as part of Procedural Page foo.php, and class baz will be documented as class baz. phpDocumentor interprets the first DocBlock in a file as a Procedural Page-Level DocBlock, or page-level DocBlock, if and ONLY if it does not precede any elements before the next DocBlock.
/**
* Page-level DocBlock
*
* This procedural page contains many functions that blah blah blah
*/
/**
* function or define DocBlock
*/
function blah()
{
...
}
The following is an example of a NON-page-level DocBlock
/**
* Almost a Page-level DocBlock
*
* This procedural page contains many functions that blah blah blah
*/
define("screwedup",66);
/**
* function or define DocBlock
*/
function blah()
{
...
}
phpDocumentor will interpret the first DocBlock as belonging to define("screwedup",66)
rather than to the page
Global Variables can only be documented by using the @global tag in a DocBlock preceding the global variable's definition. See the manual for @global for detailed information on how to use @global to document your project's global variables.
All other elements are documented by placing the DocBlock before the element. Any valid PHP Code may be placed between a DocBlock and an element as long as it isn't another element.
/**
* DocBlock will document function blah()
*/
// random comment
$a += strpos(get_another_thingy(66,$ufta));
$ark->build($a);
// etc. etc.
function blah()
{
...
}
The code below is a sample class showing phpDocumentor in action
phpDocumentor can parse any valid PHP code, but it is recommended to follow this style for ease of programming for both you and people who will be using your packages
/**
* A sample page-level DocBlock
* The package tag applies to all global variables, functions, defines and includes in this page
* @package pagetest
*/
/**
* A sample global variable
* @global array $GLOBALS['sample']
* @name $sample
*/
$GLOBALS['sample'] = array('1',2,"3","4" => 5);
/**
* A sample class
*
* This class is just random php used as a {@link http://phpdocu.sourceforge.net phpdoc} example.
* To see the $sample variable, you must use the command-line option --parseprivate or click the
* box in the web interface
*
* @version 1.0
* @author Joshua Eichorn <jeichorn@phpdoc.org>
* @package test
*/
class phptestclass
{
/**
* not parsed unless you use -pp on
* @access private
*/
var $privatevar;
/**
* A sample class variable
* @var string
*/
var $sample;
/**
* The class constructor
*
* This sets up the class and does other random stuff
*/
function phptestclass()
{
$this->sample = "test";
}
/**
* A test function
*
* This function returns {@link $sample}
*
* @see set(), $sample
* @global array used to get some sample stuff
* @return string
*/
function test()
{
global $sample;
return $sample == $this->sample;
}
/**
* Set the sample var
*
* @param string $var
* @see phptestclass::$sample, phptestclass::test()
*/
function set($var)
{
$this->sample = $var;
}
}
/**
* This function is in the page package, which is "pagetest" and not "ignored"
*
* this @package tag is ignored - only the page-level tag is parsed.
* @staticvar phptestclass an example of our static documentation
* @package ignored
*/
function inPagePackage()
{
static $mememe;
$mememe = new phptestclass;
}
From the README:
You can have multiple directories and multiple files, as well as a combination of both options
if you run phpdoc and get :
bash: ./phpdoc: No such file or directory
Then you haven't installed the cgi version of php
goto your php src dir and try
make clean
./configure
make
make install
phpdoc should work now
If your usinging php 4.2.0 or higher you might want to make the cli version
instead of the cgi. Checkout php.net for details on these changes
Command-line switches | ||
---|---|---|
-o | --output | output information, format:converter:template (HTML:default:DOM\l0l33t for example) |
-ct | --customtags | comma-separated list of non-standard @tags to pass to the converter as valid tags |
-d | --directory | name of a directory(s) to parse directory1,directory2 |
-dh | --hidden | set equal to on (-dh on) to descend into hidden directories (directories starting with '.'), default is off |
-dn | --defaultpackagename | name to use for the default package. If not specified, uses 'default' |
-f | --filename | name of file(s) to parse ',' file1,file2. Can contain complete path and * ? wildcards |
-i | --ignore | file(s) that will be ignored, multiple separated by ','. Wildcards * and ? are ok |
-q | --quiet | do not be verbose |
-pp | --parseprivate | parse elements marked private with @access. Use on/off, default off |
-po | --packageoutput | output documentation only for selected packages. Use a comma-delimited list |
-t | --target | path where to save the generated files |
-ti | --title | title of generated documentation, default is 'Generated Documentation' |
-j | --javadocdesc | use JavaDoc-compliant description (short desc is part of description, and is everything up to first .) |
From the README:
Put phpdoc.php together with the *.inc files someplace on your webserver where it can read them. NEVER USE THE WEB INTERFACE ON A PRODUCTION WEBSERVER. Allowing your server to write files to disk is a serious security risk, and phpDocumentor is not designed to work on non-secure systems. Setup php on a development machine and run phpDocumentor from there. Make sure you webserver can write to where ever you specify as a target or you will get lots of errors