O'Reilly logo

PHP Hacks by Jack D. Herrington

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

Hack #85. Generate Documentation Automatically

Use PHPDoc comments to document your code, and use the phpDocumentor to build your documentation from code comments.

JavaDoc is the commenting standard for Java, and it is used to generate documentation for Java classes automatically. This comment-to-documentation idea was so popular that now almost every language has a comment markup that can be used to automatically generate documentation.

For PHP, there's PHPDoc; it makes writing programmers' documentation for your classes much easier for everyone involved. phpDocumentor (http://www.phpdoc.org/) is an open source tool that parses PHP code, extracts the PHPDoc documentation, and generates HTML from the source, all with a variety of different styles. Figure 8-7 illustrates how PHPDoc takes PHP files as input—in this case, Author.php—and creates a set of HTML files as a documentation package.

The PHPDoc workflow

Figure 8-7. The PHPDoc workflow

The Code

Save the code in Example 8-17 as Author.php.

Example 8-17. The PHPDoc marked-up Author class

<?php
/**
 * An author class
 */
class Author
{
		/**
		 * Gets the name of the author
		 */
		function getName() { }

		/**
		 * Sets the name of the author
		 * @param string $name The name of the author
		 */
		function setName($name) { }
}
?>

Running the Hack

In this case, running the code means running the phpDocumentor command on the PHP files in your project. The Author.php file is an example ...

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required