English
do, 05/19/2005 - 23:58

HOWTO Install and use PHPDoc 

This article was first written in May 2005 for the BeezNest technical
website (http://glasnost.beeznest.org/articles/260).

Introduction

This article is meant for busy people who want to have a go at phpDocumentor. It was written after an install on Windows XP equipped with EasyPHP, but should be very similar in other situations (it's just a set of PHP scripts after all).

Getting the files

Go get the files on the PHPDoc server (or if you have an OS-specific package, use it). You can grab it from here. Unzip the file and put the directory into your web root (with EasyPHP 1.8, the default is C:Program FilesEasyPHP1-8www). You should now be able (with EasyPHP actually running) to get to the PHPDoc interface by querying http://localhost/phpDocumentor-1.2.3/.

Setting it up

That's the first tricky bit. To actually make it work, you need three things:
  • The working directory (usually set to the default of c:program fileseasyphp1-8wwwphpdocumentor-1.2.3docbuilder )
  • In "Files" tab, the directory to parse (probably something like c:program fileseasyphp1-8wwwmy_sources_directory)
  • In "Output" tab, the output directory (where your doc will be written - something like c:program fileseasyphp1-8wwwmydoc)
Once this is setup, you should be able to click the Create button in the lower right corner. That should generate your documentation. Now if you want to have a nice shortcut for next time, just bookmark the processing page, as it contains every parameter in the URL, so you will not need to do anything.

The PHPDoc documentation stuff

To have a nice documentation, you should remember three things:
  • use a file-level comment AND at least a block-level comment
  • use the @package tag in file-level comments
  • use documentation blocks of this format:
/**
 * Write a short description here
 *
 * Write a long descrition here, as many lines
 * as you like
 * @package     yourcompany[.the_script_category[.more_defined_category[.blablabla[.blabla[...]]]]]
 * @author      your_name <your_address@domain.com>
 * @todo        One stuff to do in this file (use multiple @todo tags for more)
 */

/**
 * Description of the start of your file.
 *
 * This kind of docblock is better suited for functions, classes and methods,
 * but you must put one (even a blank one) after the page-level block,
 * otherwise it will generate a warning. In this case, let's use some tags as
 * if we were commenting out a function.
 * One can also use HTML in comments for example to <em>emphasize a text</em>.
 * @param   string   $my_string A string parameter the user must pass to the function
 * @param   integer  An integer parameter the user must pass to the function
 * @return  boolean  The value returned by the function (e.g. "True on success, false otherwise").
 * @author  Another author than the file author?
 * @todo    Something to do in this function code?
 */
function my_function($my_string, $my_int){ ...
I think the @package tag is mandatory. All other tags are optional.

Install conclusion

If you respected all these steps, you should now have a wonderful documentation available at http://localhost/mydoc/ Enjoy…

Using the generated doc

You should first try to focus on why you need this doc. I got three scenarii which can help you use the doc at its best, depending on your need.

Pratical cases analysis

Problem A You have just been recruited by a company which has already a huge number of lines of code but no documentation. You will probably need to work on the existing code to fix it or reuse some to develop new features. You thus need to have an index of all existing functions/classes to understand, for example, what the wxyz() function does. Solution
  • Click on [All elements] on the top-right corner (this might change depending on the layout you have been using), then click on [w] to get directly to all elements starting with 'w'.
  • Scroll a bit and find the function.
  • Click on its name.
  • You get a small explanation of what it does. You also get the file where it is located (so you know where to look for more),
Problem B You want to have a short list of the points you need to get fixed for the next version of your code. Solution
  • Use the @todo tags in your comments before generating the doc.
  • In the doc, click on todo on the upper left corner to get to the nice list you wanted
Problem C You want to categorize your software (settings files, administration interface, user interface, ...) Solution
  • Use the @package tags in your page level comments before generating the doc.
  • Click on the package name on the left menu of the doc. You get a list of features of this package (depending on your comments structure).
  • Click on the [index: package] link in the upper right corner to get a list of all files and functions.