Glen Scott – Keeping it simple

PhpDocumentor in 5 minutes

February 18, 2009 by Glen. Filed under php.

Introduction

This is a quick and dirty guide to the absolute minimum you need to get up and running with PhpDocumentor.

One of the slightly off-putting aspects of PhpDocumentor is the amount of tags (`@`) that are available, which can initially be overwhelming. e.g. see PEAR example:

PEAR sample file

This guide shows you the most important tags that you need to have in your documentation by means of an actual example: `Accumulator.php`.

Assumptions

• You are on a UNIX based machine, which includes Linux and Mac OS X.
• You are documenting object oriented rather than procedural code

Install

PhpDocumentor is part of PEAR. Install is easy:

    sudo pear install phpdocumentor

Documenting your source code

The rules:

• One class per file
• One docbook block for the class, not for the file
• Filename is `.php`

For the class:

• short description
• code example
• `@author`

For each attribute:

• short description
• `@var`

For each method:

• short description
• `@param`
• `@return`
• `@see`

Example class with documentation

Accumulator.php

    <?php

    /**
     * An instance of this class represents a counting machine
     *
     * 
     * require_once 'Accumulator.php';
     *
     * $acc = new Accumulator( 10 );
     *
     * $acc->addNum( 20 );
     *
     * echo $acc->getTotal();
     * 
     *
     * @author Glen Scott 
     */
    class Accumulator {
        /**
         * The running total
         *
         * @var int
         */
        private $_number;

        /**
         * Create an instance, optionally setting a starting point
         *
         * @param int $initial an integer that represents the number
         *                     to start counting from
         * @access public
         */
        public function __construct( $initial = 0 ) {
            $this->_number = $initial;
        }

        /**
         * Adds a number to the running total
         *
         * @param int an integer to add to the running total
         */
        public function addNum( $num ) {
            $this->_number += $num;
        }

        /**
         * Returns the current total
         *
         * @return int returns the current running total
         * @see Accumulator::$number
         */
        public function getTotal() {
            return $this->_number;
        }
    }

Creating your documentation

phpdoc –filename Accumulator.php –target docs

The `”docs”` directory is created and some HTML files are generated. Load `docs/index.html` into your browser to read your documentation.

Possible issues

`”phpdoc: command not found”`. This means that the documentation generator script is not in your path. Run `”pear config-get bin_dir”` and add this directory to your shell’s `$PATH` environment variable.

Links

• PhpDocumentor

Tags: documentation, php, tutorial

• PHP Best Practices #1: Regular expressions →
• ← Steve Krug on Usability Testing