Pré-requis

PHPDoc nécessite PHP3.0.8+. PHP4.0.3+ est fortement conseillé. Les modules suivants doivent être activés:

• XML - Expat
• Perl Compatible Regular Expressions - PCRE

Etapes

La version 1.0 beta ne contient aucun utilitaire d'installation ni interface graphique. Il est probable que les versions futures améliorent la convivialité. Actuellement vous devez effectuer les étapes suivantes:

1. Téléchargez PHPDoc
2. Dézippez le fichier
3. Modifiez votre fichier php.ini pour accepter les temps d'exécution longs
4. Configurez index.php
   1. Régler le temps maximum d'exécution
   2. Régler PHPDOC_INCLUDE_DIR et LINEBREAK

PHPDoc is not very fast. A PII-500 needs slighly more than 30 seconds for 10.000 lines of code (PHPDoc: ~10.500loc). 30 seconds is the default value for the maximum execution time in the php configuration file which is usually named php.ini for PHP4 and php3.ini for PHP3. That means it's likely that PHPDoc will not be able to document itself if you don't change the default value. By the way on my development server "KROETE" which is an AMD5x86-133 (~P75) running windows the documentation of PHPDoc takes about 350 seconds.

Snippet from my php.ini

;;;;;;;;;;;;;;;;;;; ; Resource Limits ; ;;;;;;;;;;;;;;;;;;; max_execution_time = 480 ; Maximum execution time of each script, in seconds (UNIX only) memory_limit = 8388608 ; Maximum amount of memory a script may consume (8MB)

Edit your php.ini (max_execution_time) file or use set_time_limit() to set whatever maximum execution time you need. See the above figures to get an idea of how much time a certain task needs. I suggest at least 60 seconds for PIII, 120 seconds for PII/Netra T1, 240 seconds for PI-200 machines and 480 seconds for relatives of KROETE.

Configuring index.php4

The script needs two constants to be defined:

Head of index.php4

// Directory with include files define("PHPDOC_INCLUDE_DIR", "c:/www/apache/doc/"); // Important: set this to the Linebreak sign of your system! define("LINEBREAK", "\r\n");

PHPDOC_INCLUDE_DIR is used in prepend.php which includes all the files that build PHPDoc (about 50). Depending on your system it contains an absolute or relative path to the PHPDoc installation directory. In Most cases you can't go wrong when you use a full (absolute) path e.g. c:/www/apache/phpdoc/... or /home/www/servers/... .

LINEBREAK is used by the XMLReader/XMLWriter to distinguish between line breaks and simple carriage return (\r) or line feed (\n) characters without any special meaning to PHPDoc.

If you don't know the line break sign on your system create a file containing one and read out the file using fopen(), ord() and substr(). This is a good exercise for beginners anyway ;-). Please tell me what you have found out, so that we can have a table here with your results.

Configuration is finished now. See the section on the usage for an example on how to let PHPDoc document itself.

 Usage

Usage will be described on a practical example: let's tell PHPDoc to document itself. The example requires that you have followed the instruction given in the installation section.

1. set the name of you application
2. set the directory with you source files
3. set the directory where to save the generated docs
4. set the directory where the templates reside
5. tell PHPDoc the suffix of your source files

setApplication() in index.php4

// Sets the name of your application. // The name of the application is used e.g. as a page title $doc->setApplication("PHPDoc");

Customizing starts with setApplication() (of course you can change the order if you preferr any other...). setApplication() tells PHPDoc the name of your application you're going to scan. This might be "PEAR Repository", "PHPLib", "PHPDoc" or whatever you are trying to document with PHPDoc. The name you're giving get's used on many places in the default HTML template, for example as a page title.

setSourceDirectory() in index.php4

// directory where your source files reside: $doc->setSourceDirectory(PHPDOC_INCLUDE_DIR);

setSourceDirectory() tells PHPDoc where your (php) source files reside. If you did not change the directory structure in the distribution and followed the previous steps this is PHPDOC_INCLUDE_DIR in our example. The directory an all it's subdirectory will be scanned.

setTarget() in index.php4

// save the generated docs here: $doc->setTarget(PHPDOC_INCLUDE_DIR."apidoc/");

PHPDoc saves the generated documentation in the directory that you specify with setTarget(). Some XML and HTML files will be created that can be used to build the frameset you can see on the demo pages.

The script will not create an frameset (index.html) nor place a style sheet file in the target directory. To browse the API documentation copy index2.html and phpdoc.css from the directory apidoc/keep/ to the target directory.

Note: PHPDoc uses all XML files it finds in apidoc/ to render the docs. That means if you leave XML files from a previous run in the directory PHPDoc will generate HTML from these files although you did ask it to document only certain (new) files.

setTemplateDirectory() in index.php4

// use these templates: $doc->setTemplateDirectory(PHPDOC_INCLUDE_DIR."renderer/html/templates/");

setTemplateDirectory() tells PHPDoc where your templates reside. By default the templates in PHPDOC_INCLUDE_DIR."renderer/html/templates/" get used. PHPDoc uses a template class called "IntegratedTemplate" (IT[X]) from the PHPLib.

You can modify the template in whatever way you want as long as you do not change the nesting of the blocks. If you e.g. dislike the idea of public/private just remove the {ACCESS} placeholder.

setSourceFileSuffix() in index.php4

// source files have one of these suffixes: $doc->setSourceFileSuffix( array ("php", "inc") );

As said PHPDoc will recursively scan the directories you specified with setSourceDirectory() and parse all the files with a certain file suffix ( filename.[suffix] ). The allowed suffix for source files gets set by setSourceFileSuffix().

That's it.$doc->parse() runs the Parser/Analyser, $doc->render() starts the only available template based HTML Renderer.

Doc Comments

A Doc Comment is a special case of an multiline comment that stands in front of certain keywords.

Structure of a Doc Comment

/** * Short description - used in indexlists * * Multiple line detailed description. * The handling of line breaks and HTML is up to the renderer. * Order: short description - detailed description - doc tags. * * @param string Target directory for the generated HTML Files */

... to be continued.