Q: Why do we need another Javadoc clone for PHP?

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 spend hours reading documentation and tweaking my PHP code. The PHP tokenizer extension has made creating PHPDoc programs really easy since PHP can now do the hard work for you.

Q: Why is PHPDoctor different from other PHPdoc programs?

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.

Q: Tell me more about how PHPDoctor works

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, turns them into an object hierarchy and finally into your 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, copy and edit the default config file and then run phpdoc.php with your CLI version of PHP (the CGI version may also work from the commandline):

php phpdoc.php myconfig.ini

To get PHPDoctor to work, you first need to write a configuration file for the code you want to parse. Copy and edit the default config file, it is commented and pretty straight forward to understand.

PHPDoctor supports a number of configuration directives:

files

Names of files to parse. This can be a single filename, or a comma separated list of filenames. Wildcards are allowed.

ignore

Names of files or directories to ignore. This can be a single filename, or a comma separated list of filenames. Wildcards are NOT allowed.

source_path

The directory to look for files in, if not used the PHPDoctor will look in the current directory (the directory it is run from).

subdirs

If you do not want PHPDoctor to look in each sub directory for files uncomment this line.

quiet

Set how loud PHPDoctor is as it runs. Quiet mode suppresses all output other than warnings and errors.

verbose

Set how loud PHPDoctor is as it runs. Verbose mode outputs additional messages during execution.

doclet

Select the doclet to use for generating output.

doclet_path

The directory to find the doclet in. Doclets are expected to be in a directory named after themselves at the location given.

taglet_path

The directory to find taglets in. Taglets allow you to make PHPDoctor handle new tags and to alter the behavour of existing tags and their output.

default_package

If the code you are parsing does not use package tags or not all elements have package tags, use this setting to place unbound elements into a particular package.

overview

Specifies the name of a HTML file containing text for the overview documentation to be placed on the overview page. The path is relative to "source_path" unless an absolute path is given.

package_comment_dir

Package comments will be looked for in a file named package.html in the same directory as the first source file parsed in that package or in the directory given below. If package comments are placed in the directory given below then they should be named ".html".

globals

Parse out global variables.

constants

Parse out global constants.

private

Generate documentation for all class members

protected

Generate documentation for public and protected class members

public

Generate documentation for only public class members

d

The directory to place generated documentation in. If the given path is relative to it will be relative to "source_path".

windowtitle

Specifies the title to be placed in the HTML

doctitle

Specifies the title to be placed near the top of the overview summary file.

header

Specifies the header text to be placed at the top of each output file. The header will be placed to the right of the upper navigation bar.

footer

Specifies the footer text to be placed at the bottom of each output file. The footer will be placed to the right of the lower navigation bar.

bottom

Specifies the text to be placed at the bottom of each output file. The text will be placed at the bottom of the page, below the lower navigation bar.

tree

Create a class tree

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-text

Some 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 through our Github issue tracker.

The only way to make PHPDoctor a better product is to test it against more and more PHP code. We think PHPDoctor is pretty good at doing its job, it works against all the libraries we've tried it on, but then again you might write something wierd that causes it to barf, so let us know how it faired against your code.

Access to Git

If your hunting bugs, grab the latest version from Github or directly via Git:

git clone git://github.com/peej/phpdoctor

The information below applies to everything in the 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.