Home arrow PHP arrow Page 4 - Writing Self-Documenting PHP Code

I, Robot - PHP

Are 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.

TABLE OF CONTENTS:
  1. Writing Self-Documenting PHP Code
  2. Speaking In Tongues
  3. Drilling Deeper
  4. I, Robot
  5. Tonight's Menu
  6. Different Strokes
  7. Closing Time
By: Harish Kamath, (c) Melonfire
Rating: starstarstarstarstar / 14
April 15, 2002

print this article
SEARCH DEV SHED

TOOLS YOU CAN USE

advertisement
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:



 
 
>>> More PHP Articles          >>> More By Harish Kamath, (c) Melonfire
 

blog comments powered by Disqus
escort Bursa Bursa escort Antalya eskort
   

PHP ARTICLES

- Hackers Compromise PHP Sites to Launch Attac...
- Red Hat, Zend Form OpenShift PaaS Alliance
- PHP IDE News
- BCD, Zend Extend PHP Partnership
- PHP FAQ Highlight
- PHP Creator Didn't Set Out to Create a Langu...
- PHP Trends Revealed in Zend Study
- PHP: Best Methods for Running Scheduled Jobs
- PHP Array Functions: array_change_key_case
- PHP array_combine Function
- PHP array_chunk Function
- PHP Closures as View Helpers: Lazy-Loading F...
- Using PHP Closures as View Helpers
- PHP File and Operating System Program Execut...
- PHP: Effects of Wrapping Code in Class Const...

Developer Shed Affiliates

 


Dev Shed Tutorial Topics: