I, Robot - PHPAre you the kind of person who hates documenting your sourcecode? Does the thought of writing API documentation make your eyeballscontract and your toes itch? Well, itch no more - this articledemonstrates how you can use PHPDoc to automatically generate APIdocumentation using the comments in your source code.
print this article SEARCH DEV SHED |
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: 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: 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: 
blog comments powered by Disqus |
/ 14 
PHP Closures as View Helpers: Lazy-Loading File Data
