NAME
	PHPDoctor: The PHP Documentation Creator
	Peej's Quick & Dirty PHPDoc Clone

VERSION
	1.4

DESCRIPTION
	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.
	
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 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.
	
	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 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 - PHPDoc script
	default.ini - Default ini file
	templates/default/class.php - Class documentation template
	templates/default/index.php - Documentation frameset
	templates/default/interface.php - Interface documentation template
	templates/default/overview-frame.php - Package side frame
	templates/default/overview-summary.php - Documentation summary template
	templates/default/overview-tree.php - Overview class tree template
	templates/default/package-constants.php - Constant documentation template
	templates/default/package-frame.php - Documentation side frame
	templates/default/package-functions.php - Functions documentation template
	templates/default/package-globals.php - Globals documentation template
	templates/default/package-summary.php - Package summary template
	templates/default/package-tree.php - Package class tree template
	templates/default/stylesheet.css - Stylesheet

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 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 .php
	* file_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.

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.

		paul@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.