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.

<< Installation| Doc Comments >>