--------------------------------------
README file since release 0.9
--------------------------------------

Table of contents

1. PURPOSE
2. FILE LIST
3. WRITE A COMMENTED SOURCE FILE
4. SUPPORTED TAGS
5. SUPPORTED TYPES

---------------------------
1. PURPOSE
---------------------------

The purpose of this package is to generate a set of HTML pages
that contain the API documentation parsed from a set
of PHP source files. This tool is similar to Javadoc, but
designed for PHP.
This packages is distributed under the GNU GPL licence terms.

---------------------------
2. FILE LIST
---------------------------

AUTHORS                       list of authors
CHANGES                       changes between versions
COPYING                       the GNU GPL licence terms
INSTALL                       how to install this soft?
README                        this file
src/                          the sources

---------------------------
3. WRITE A COMMENTED SOURCE FILE
---------------------------

Only the special comment blocks are recognized by phpdocgen :
  /**
    *  This is a multi-line comment PARSED by phpdocgen
    */

  /*
    *  This is a multi-line comment IGNORED by phpdocgen
    */

  //* This is a mono-line comment PARSED by phpdocgen

  // This is a mono-line comment IGNORED by phpdocgen

The following PHP source shows an example of documentation which
could be used by phpdocgen to generate a whole of HTML pages :

          <?php

          /**
            * Updating delay of the User cookie (in minutes).
            *
            * @constant USER_COOKIE_UPDATE_DELAY
            * @package advanced/account/user
          */
          define( USER_COOKIE_UPDATE_DELAY, 5 ) ;

          /**
            * This class represents an user.
            *
            * @package advanced/account/user
          */
          class User extends Buffereddbobject {

             /**
               * Constructs a new User.
               *
               * @use USER_TABLE_DEF
             */
             function User() {
                global $USER_TABLE_DEF ;
                ...
             }

             /**
               * Replies if the current user is same as
               * the specified user.
               *
               * @param object user is the user
               * @return <code>TRUE</code> if
               *     the specified user is the same
               *     as the current.
             */
             function sameuser( $user ) {
                return FALSE ;
             }

          } ?>

Each comment supported by phpdocgen must preceed the source code
which is commented. This is very important, because phpdocgen try
to parse the source code that follows each comment to determine
what is commented.

---------------------------
4. SUPPORTED TAGS
---------------------------

phpdocgen supports a whole of internal commands which influence
its behaviour.
Inside your shell, type 'perldoc phpdocgen.pl' to obtain the
lastest updates on the supported tags.

   @attribute type identifier
       The current comment is for an class attribute named identifier.
       You must use the tag @class to specified the class in which this
       attribute is.

    @author text
       An author of the currently documented stuff is described by
       the text.

    {@block text}
       The specified text is considered as a unsplitable block of text.

    @brief [comment]
       Sets the brief description for the documented object. If this 
       tag was not given, the first sentence of the description will 
       be the brief description.

    @class identifier
       The currently documented stuff is a member of the class
       (attribute, method...), or is the class identifier. In this 
       last case, you could use the tag @package to specified the
       package in which this class is (if not, the default package
       will be used).

    @constant [type] identifier
       The currently documented stuff is a global constant named 
       identifier. You could use the tag @package to specified the 
       package in which this constant is (if not, the default package
       will be used).

    @constructor identifier
       The currently documented stuff is the constructor for the class
       identifier.

    @copyright description
       Sets a copyright comment about the documented object.

    @date date
       Sets the creation (or last-update) date of the documented object.

    @deprecated [text]
       The currently documented stuff is deprecated. text is the explanation.

    @extends identifier
       The documented class inherites from the class identifier. You must
       use the tag @class to specified the child class.

    @function identifier
       The current comment is for a global function named identifier. You 
       could use the tag @package to specified the class in which is this 
       attribute (if not, the default package will be used).

    {@hash [key] [comment]}
       Ignored. Reserved for futher use.

    @inherited identifier
       See @extends

    {@link name [comment]}
       Adds a link to the documentation of name with the comment.

    @method [static] identifier
       The current comment is for an class method named identifier. 
       You must use the tag @class to specified the class in which this 
       method is. If "static" is present, it applies that this method is 
       static, i.e. the use of the variable $this is not allowed.

    @package identifier
       The currently documented stuff is a member of the package identifier.

    @param [optional] type identifier [comment]
       Adds a parameter comment for the current documented stuff. The 
       parameter has named identifier and is commented by comment. If 
       optional is present, the parameter is optional.

    @return [type] comment
       Explains what is return by the current documented function.

    @see comment
       Gives a pointer to another documentation. If comment is a valid
       name, show a link to the corresponding documentation page.

    @since comment
       Explains from when the current comment is exists.

    @todo comment
       Adds a comment about something to do on the current documented object.

    @use name
       Indicates that the current function uses the global variable name.

    @variable type identifier
       The current comment is for a global variable named identifier. You 
       could use the tag @package to specified the package in which this
       variable is (if not, the default package will be used).

    @verbatim
       The explanation of the current comment will be putted as-is in 
       the generated documentation. The generated explanation will be 
       enclosed by <PRE> and </PRE>.

    @version comment
       Describes the version of the documented object.

---------------------------
5. SUPPORTED TYPES
---------------------------

phpdocgen supports a whole of types.
Inside your shell, type 'perldoc phpdocgen.pl' to obtain the
lastest updates on the supported types.

str
string

bool
boolean

flt
float

int
integer

array           a set of values, which are indexed by integers,

hashtable
hash            a set of values, which are indexed by string keys,

obj
object          the instance of a class,

timestamp
date
time            a unix timestamp, i.e. the quantity of seconds since the 1970/01/01,

mix
mixed           a value that could have one of the other types.
