PHPDoctor is a Javadoc style comment parser for PHP, written with an emphasis on speed and simplicity. It is not as fully featured as other PHPDoc programs, but is simple to configure, use, and extend.
PHP 4.3.0+ is required due to use of the PHP tokenizer extension. The tokenizer is built into PHP 4.3.0 by default, this program may work with older versions of PHP with the tokenizer extension enabled but it has not been tested and you are recommended to upgrade to 4.3.0+ for using this program.
A: I wrote PHPDoctor because I couldn't find a Javadoc clone for PHP that was small and simple and worked out of the box without having to understand how numerous templating engines work, or that worked correctly on my code. The PHP tokenizer extension has made creating PHPDoc programs really easy since PHP can now do the hard work for you.
A: PHPDoctor is very small and easy to use, even the templating layer it uses for output generation is small and simple to understand. PHPDoctor has a very small learning curve, most people should be able to generate API documentation in only a few minutes.
A: PHPDoctor uses the PHP tokenizer extension, this means that it lets PHP do the parsing of your source code. PHPDoctor just takes the tokens PHP parses out and turns them into API documentation. This means it will work for any PHP code, no exceptions, it also makes it very fast. The down side of this is that it needs PHP 4.3 or above to work.
Unzip the archive somewhere, edit the default config file and then run phpdoc.php with your CLI version of PHP.
phpdoc.php - PHPDoc scriptdefault.ini - Default configuration filetemplates/default/class.php - Class documentation templatetemplates/default/index.php - Documentation framesettemplates/default/interface.php - Interface documentation templatetemplates/default/overview-frame.php - Package side frametemplates/default/overview-summary.php - Documentation summary templatetemplates/default/overview-tree.php - Overview class tree templatetemplates/default/package-constants.php - Constant documentation templatetemplates/default/package-frame.php - Documentation side frametemplates/default/package-functions.php - Functions documentation templatetemplates/default/package-globals.php - Globals documentation templatetemplates/default/package-summary.php - Package summary templatetemplates/default/package-tree.php - Package class tree templatetemplates/default/stylesheet.css - Stylesheetphpdoc.php <config_file>
If you are using MS Windows and don't have the .php file type registered with the PHP CLI executable, you will need to call the PHP executable explicitly as in:
c:\php\cli\php.exe phpdoc.php <config_file>
To create a config file for your project, copy the default.ini file and edit it to your needs, it's fully commented.
PHPDoctor supports a number of configuration directives:
files is a list of PHP files for PHPDoctor to parse, this directive must be supplied, can contain a number of filenames separated by commas, and can contain wildcards. For example "*.php" will read all files ending in .phpfile_path is the path to look for the files specified in "files", if not given the current directory is used (the directory PHPDoctor is being run from). All paths in other directives if given as relative paths will be relative to the directory given in this directive.subdirs if set to "on" tells PHPDoctor to look in subdirectories of the directory given in "file_path" to find files to parse.file_list is the filename of a text file listing files to parse, one filename per line, this directive should be used instead of "files".output_dir is the directory to create the documentation in.title is the title for your documentation, this will be visible on the overview page and in document titles.short_title is a short title for your documentation, this is used on every page.overview_comment is the path/filename of a HTML file to use for adding a documentation comment to the overview page of the documentation.package_comment_dir is the path to look in for package comments, they must be HTML files named packageName.html to be found correctly.footer is a string to place at the foot of every page of your documentation.default_package is the name of the package to place objects without a explicit package tag set.template is the name of the output template to use, new templates should be placed in the templates directory for PHPDoctor to find them.globals if set to "on" global variables will be documented also.constants if set to "on" global constants will be documented also.tree if set to "on" a class hierarchy tree will be generated.warnings if set to "false" will suppress warnings generated by missing expected tags and other parsing errors.hide_private if set to "on" will not generate documentation for private member variables and methods.A full description of the format of doc comments can be found on the Sun Javadoc web site. Doc comments look like this:
/** * This is the typical format of a simple documentation comment * that spans two lines. */
Note the extra asterisk after the opening comment line.
PHPDoctor supports most of the Javadoc tags defined by Sun. The following tags are supported:
@abstract@access access-type@author name-text@deprecated deprecated-text@final{@link package.class#member label}{@linkplain package.class#member label}@package package-name@param parameter-type parameter-name description@return return-type description@see package.class#member@since since-text@static@var var-type@version version-textSome Javadoc tags are not relevant to PHP and so are ignored, others are added or slightly changed due to PHPs loose typing:
@abstract is a new tag defining a class or method as abstract.@access is a new tag and is valid within field and method doc comments. The first word after the tag should denote the access type of the field or method.@final is a new tag defining a class or method as final.@package is a new tag that places an item into a specific package and is valid within any doc comment of a top level item.@param has a parameter-type value added as the first word after the tag. This value should denote the data type of the parameter.@return has a return-type value added as the first word after the tag. This value should denote the methods or functions return data type.@static is a new tag defining a class, method or member variable as static.@var is a new tag and is valid within field doc comments. The first word after the tag should denote the data type of the field.@type is a synonym for @var.If you find PHPDoctor useful, have found a bug, or want to request a feature, please get in touch either via e-mail or through our Sourceforge project page.
The information below applies to everything in this distribution, except where noted.
Copyright 2004 by Paul James. paul at peej.co.uk http://www.peej.co.uk/ This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program 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 General Public License for more details. You should have received a copy of the GNU General Public License along with this program (COPYING); if not, go to http://www.fsf.org/ or write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.