Generating API docs automatically with phpDocumentor

by Guest Contributor | Aug 31, 2004 7:00:00 AM

Takeaway: Developers hate writing documentation, which is why there are tools like phpDocumentor. It creates documentation from your PHP code by reading special identifiers and comments in the code itself. We'll show you how to mark up your scripts, and generate a class tree and method/property information from your code.

Developers and documentation are like oil and water�they just don't mix well. Many developers find writing documentation to be a boring waste of time. It's no wonder, then, that most companies hire separate personnel to create technical documentation rather than try to persuade developers and programmers to do it themselves.

But for those of you developing with PHP, there is a solution called phpDocumentor. Similar to Java's javadoc tool, phpDocumentor automatically creates API documentation by reading special identifiers and comments embedded in your PHP code. Since most good developers routinely use comments in their code anyway, the additional burden on them is minimal. And phpDocumentor can output its documentation in a variety of formats (including HTML, XML, and PDF), further reducing the time spent on manual documentation. Of course for more sophisticated documentation like user manuals or process flow diagrams you still need a technical writer. But for simple class documentation and method prototypes, phpDocumentor is a very adequate tool.

In this crash course, I'll start by showing you the special identifiers and syntax you can use when marking up your scripts. I'll also show you the basics of using phpDocumentor to read your code and automatically generate a class tree and method/property information from it.

A complete solution

Billed as "the complete documentation solution for PHP", phpDocumentor works by reading your source code for comments and then using those comments to create professional, neatly-formatted API documentation. It supports a variety of different output formats: HTML, PDF, Windows HLP, and XML. Within each of these output formats, different templates and designs are available. And you can even create your own templates�phpDocumentor uses the well-known Smarty template engine to render the data.

phpDocumentor is available through PEAR, the PHP Extension and Application Repository, and it can also be downloaded from Phpdoc.org. To install it, simply extract the files in the download archive to your local installation of PEAR and point your browser to the phpdoc.php script in the installation directory. You should see something like Figure A.

Figure A

Primary Web interface to phpDocumentor

This form is the primary Web interface to phpDocumentor (there's also a command-line interface, but we'll focus on the GUI), and you'll use it to tell the application which PHP classes to read and generate documentation for. More on that later, though�first, let me show you how to use phpDocumentor syntax to mark up your code.

Turning up the heat

Consider the simple function definition in Listing A.

This code is a PHP function definition, with both arguments and a return value. To have phpDocumentor generate documentation from this, you need to mark it up with some more information, as show in Listing B.

Sure, it looks impressive...but what does it actually mean?

The basic element of phpDocumentor markup is a so-called DocBlock�a multiline comment block�which can appear before any PHP construct, class, or function and looks like this:

/**
�* text here
�*
�*/

Within this DocBlock, phpDocumentor allows three types of items: a short description; a longer description; and a series of special tags each prefixed with an @ symbol as in the example in Listing C. These tags are optional; however, it's a good idea to include them to help make the final documentation more precise. Some of the more commonly-used tags supported by phpDocumentor, and what each represents:

@access: whether the function is private or public
@author: the name and e-mail address of the function author
@version: the version number of the function
@copyright: copyright information for the function, if needed
@package: the package the function belongs to, if available
@param: argument to a function, including its type and a description
@return: return value from a function, including its type and a description
@var: the variable type and description, for class variables or local variables inside a function
@global: the variable type and description, for global variables inside a function
@see: name of another, related element
@todo: items still to be completed

There is no hard and fast rule about which tag appears where, but a general rule of thumb is to use only relevant tags to avoid cluttering up the final document. For example, it makes sense to use @param and @return for functions and methods, but is inappropriate to use these two tags for variable definitions. The phpDocumentor Web site offers more detailed guidelines.

Many hands make light work

Now that you've got your code all marked up in phpDocumentor syntax, it's time to use it. Pop open your browser and head back to the phpdoc.php form you saw earlier. This time, go ahead and fill the form out�you must enter values for the target directory (where the documentation will be placed), the source directory or source file (what is to be documented), and the output format or "converter" to use (I usually choose HTML:Smarty:PHP). Once you've filled those in, submit the form and phpDocumentor will go to work generating the document.

A few hundred status messages later, you should have the documents generated and placed in the target directory. Navigate to that directory and open the index page in your browser to see something like Figure B.

Figure B

HTML output of phpDocumentor

You can click on the filename in the left frame to view its contents, Figure C.

Figure C

Documentation generated from a user-defined PHP function

Notice how all the information you provided in your tagged source code has been converted into a neatly-formatted API definition. Now let's see how this works with classes and class hierarchies.

Back to class

You've seen an example of using phpDocumentor with a user-defined function. Now, let's look at how it works with a class, like the one in Listing D.

The amount of documentation needed for the source code of a class is much more than that needed for a simple function. Typically, you will place class-level information above the class definition, and include author, version, and copyright information in the outer DocBlock; you can also include the @package tag if this class is part of a larger package. Class variables are usually marked with @var tags for data types and @access tags for private or public visibility, while class methods use @param, @return and @access tags to represent method arguments, return values, and visibility respectively.

When you run phpDocumentor on the class definition, you should get something like Figure D.

Figure D

Documentation generated from a PHP class

The source code of the class has been neatly dissected. There's a section for the class overview, a list of private and public variables, methods and method prototypes, and other useful information. Documentation like this makes it easy for other programmers to quickly understand what your class does and how it works�and how to use it without having to dig through the actual source.

OOPs

If you're an OOP programmer, it's unlikely that you'll be using stand-alone classes. It's far more likely that you'll have a class hierarchy, where objects serve as the base for new child objects with new and inherited properties and methods. phpDocumentor excels at building documentation for this type of class tree�it has built-in support for identifying dependencies between classes, and for creating links between the different hierarchies of a class API.

To understand this better, consider the extension of the AddingMachine() class shown in Listing E, and then look at some screens of what the generated API looks like (Figure E and Figure F).

Figure E

Basic documentation generated from a PHP class

Figure F

Detailed documentation generated from a PHP class

Notice how phpDocumentor has cleverly figured out that the Calculator() object is a child of the AddingMachine() object from the "extends" keyword, and has imported and linked AddingMachine() methods and properties into Calculator()'s namespace.

Linking out

phpDocumentor also comes with a bunch of tags that can be used to point a reader to additional reference material, or to related classes and functions. The simplest of these is the @see tag, which tells the reader to "see" related variables, functions, or classes. The code in Listing F demonstrates its usage.

The debit() and credit() functions will be linked to each other in the final documentation, making it easier for users to jump from one to the other. You can create as many such @see links as you like�phpDocumentor will automatically attempt to track down the target variable or function and create a link to it.

If you'd like to link to a Web page or tutorial describing the element in greater detail, use the @link tag, which is automatically converted by phpDocumentor into a hyperlink. Listing G shows how to use the tag.

When phpDocumentor encounters the @link tag in Listing G, it will create a hyperlink to the URL argument. This is great for linking to more detailed documentation elsewhere, or for putting notes and tips in your classes that can be explained in detail later.

I hope this article gave you enough information to get you started with this auto-documentation system. But this is just the tip of the iceberg. There are many more things you can do with phpDocumentor, and you can read all about them in the excellent online tutorial. I hope you'll take advantage of phpDocumentor's powerful features to save yourself some time and stress the next time you sit down to code a PHP application.

2 comment(s)