NAME
PHPDoctor: The PHP Documentation Creator
Peej's Quick & Dirty PHPDoc Clone
VERSION
2 RC4
DESCRIPTION
PHPDoctor is a Javadoc style comment parser for PHP, written with an
emphasis on speed and simplicity. It is designed to be as close a
clone to Javadoc as possible.
REQUIREMENTS
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.
Q&A
Q: WHY DO WE NEED ANOTHER PHPDOC CLONE?
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 or that worked
at all. 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, sticking as closely as
possible to the way Javadoc works, including using the same program
structure and doclet approach to templating. 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 and turns them into API documentation. This means it will
work for any valid 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.
FEATURES
* Fast running speed, uses PHP 4.3 tokenizer function to take advantage
of PHPs internal parsing functionality.
* Parsing of any valid PHP file, with multiple classes and functions in
the same file.
* Simple output template layer, allowing easy changing of the output
format by copying and editing of a few simple PHP template files.
* Simple to install and use, instant results.
* Will generates API documentation bare bones without Javadoc comments
present.
* Works with both OO and procedural code, also documents global
variables and constants.
* Supports PHP5 enhanced syntax, including interfaces (requires PHP5
to work).
* Minimal changes to Sun's Javadoc specification.
* Javadoc extensions compatible with other PHPDoc programs.
* Did I say it was fast?
INSTALLATION
Unzip the archive somewhere, edit the default config file and then run
phpdoc.php with your CLI version of PHP.
FILES
phpdoc.php - PHPDoctor commandline script
default.ini - Default ini file
README - This file
readme.html - HTML version of this file
classes/*.php - Classes used by PHPDoctor
doclets/debug/*.php - Debugging doclet
doclets/standard/*.php - Standard HTML doclet
USAGE
phpdoc.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.
CONFIGURATION
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 - Quiet mode suppresses all output other than warnings and
errors.
* verbose - 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
the directive below is used then package comments should be
named "<packageName>.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.
The following directives are specific for the standard doclet:
* 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 <title>
tag.
* 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
DOC COMMENTS
A full description of the format of doc comments can be found on the
Sun Javadoc web site (http://java.sun.com/j2se/javadoc/). Doc comments
look like this:
/**
* This is the typical format of a simple documentation comment
* that spans two lines.
*/
TAGS
PHPDoctor supports the following tags:
@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 packahge.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.
PHPDoc 1.1+ also supports the new tags @abstract, @static and @final
which correspond to the equivalent PHP5 keywords and can be used if
required.
COPYRIGHT AND LICENSE
The information below applies to everything in this distribution, except
where noted.
Copyright 2004 by Paul James.
[email protected]
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.