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:
Next: Tonight's Menu >>
More PHP Articles
More By Harish Kamath, (c) Melonfire
/ 13 
