Writing Self-Documenting PHP Code - I, Robot (
Page 4 of 7 )
With the
comment style out of the way, it's time to actually run PHPDoc on the source
code and use the comments within it to create some API
documentation.
Obviously, the first step here is to make sure that you
have a copy of the application. In case you don't, drop by the official Web site
at http://www.phpdoc.de/, and download a copy (this article uses version 1.0b).
Unzip the files within the source archive to a directory off your Web server
root, and you're ready to go (in case you have difficulty, take a look at the
README that's included in the source archive).
In order to have PHPDoc
create documentation for your classes, you need to write a simple PHP script
that instantiates an object of the PHPDoc class and uses it to write HTML files
containing the API documentation. This script is fairly standard, and one
version of it ships with the PHPDoc source archive. Here's what it looks like:
<html>
<head>
</head>
<body>
<?php
// where are the PHPDoc files?
// alter this as per your setup
define("PHPDOC_INCLUDE_DIR", "/usr/local/apache/htdocs/phpdoc/");
// system linebreak sequence
// alter this as per your setup
define("PHPDOC_LINEBREAK", "\r\n");
// include PHPDoc files
include("prepend.php");
// instantiate a PHPDoc object
$doc = new Phpdoc;
// set application name
$doc->setApplication("SandwichMaker");
// source file location
// alter this as per your setup
$doc->setSourceDirectory("/usr/local/apache/htdocs/phpdoc/SandwichMaker/
");
// destination directory for generated docs
// alter this as per your setup
$doc->setTarget("/usr/local/apache/htdocs/phpdoc/SandwichMaker/docs/");
// template location
// alter this as per your setup
$doc->setTemplateDirectory("/usr/local/apache/htdocs/phpdoc/renderer/htm
l/te
mplates/");
// source file suffixes
$doc->setSourceFileSuffix( array ("php", "inc") );
// parse
$doc->parse();
// and render
$doc->render();
?>
</body>
</html>
As you can see, the process of generating documentation with
PHPDoc is fairly simple. Most of the work consist of setting file locations (for
the source class and resulting output) via calls to the class methods
setSourceDirectory(), setTarget() and setTemplateDirectory(). Once all these
locations have been defined, the parse() method is used to scan your source code
and generate XML data from the comments within it, while the render() method is
used to convert and write this data to browseable HTML documents.
Note
that your Web server must appropriate permissions to create files in the
specified target directory.
Now, when you browse to this script via your
Web browser, you should see something like this:
Parser starts... ... preparse to find modulegroups and classtrees. ...
parsing classes. ... parsing modules. ... writing packagelist. Parser
finished. Starting to render...
Once the script has finished executing (the process takes
about thirty seconds for a medium-sized class file), take a look in the
destination directory specified via the call to setTarget() in the PHP script
above. You should see a whole bunch of XML and HTML files, which contain the API
documentation created by PHPDoc. Here's what they look like:
If this seems a little too plain-Jane for you, take a
look at the <PHPDoc>/apidoc/keep/ directory - you'll find a CSS file there
that you can use to make the output documentation look a little nicer (you can
customize this CSS file to meet your own particular requirements as well).
Here's what the documentation looks like after applying the CSS
file:
/ 14 
