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
     *
     * <code>
     * require_once 'Accumulator.php';
     * 
     * $acc = new Accumulator( 10 );
     * 
     * $acc->addNum( 20 );
     * 
     * echo $acc->getTotal();
     * </code>
     *
     * @author Glen Scott <glen @ glenscott.co.uk>
     */
    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

Glen Scott

I’m a freelance software developer with 18 years’ professional experience in web development. I specialise in creating tailor-made, web-based systems that can help your business run like clockwork. I am the Managing Director of Yellow Square Development.

More Posts

Follow Me: