peej / phpdoctor

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.

    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.