PhpDocumentor in 5 minutes

Help Point

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.

PhpDoc sample page

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


Want advice on building better software? Join my mailing list…


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:
TwitterFacebookLinkedIn

14 thoughts on “PhpDocumentor in 5 minutes

  1. Bill Hernandez

    Thank you for posting this article…

    I used pear to install, as you recommended, but keep getting this error

    Any ideas ?

    Best Regards.

    phpdoc –f Accumulator.php –t /projects/a/project_00015/docs/
    PHP Version 5.3.3
    phpDocumentor version 1.4.3

    Parsing configuration file phpDocumentor.ini…
    (found in /usr/lib/php/data/PhpDocumentor/)…

    done
    Maximum memory usage set at 256M after considering php.ini…
    using tokenizer Parser
    a target directory must be specified
    try phpdoc -h

    Reply
  2. Glen Post author

    @Bill Hernandez

    Try using the long options instead:

    phpdoc –file Accumulator.php –target /projects/a/project_00015/docs/

    Do you get the same error?

    Reply
  3. Arun Solomon

    I am getting the following error when i execute the following command:

    PHP Version 5.3.5-1ubuntu7.2
    phpDocumentor version 1.4.3

    Parsing configuration file phpDocumentor.ini…
    (found in /var/www/PhpDocumentor/)…

    done
    Maximum memory usage setting disabled by php.ini…
    using tokenizer Parser
    a target directory must be specified
    try phpdoc -h

    Reply
    1. Glen Post author

      Hi Arun,

      Try using the long options instead:

      phpdoc –file Accumulator.php –target /projects/a/project_00015/docs/

      Do you get the same error?

      Reply
  4. Rob

    You could try missing out the final forward slash (solidus) from your directory:

    phpdoc –f Accumulator.php -t /projects/a/project_00015/docs

    If you are going to use the long options, though I don’t think that’s the cause of the error, don’t forget you must precede them with two hyphens, not one:
    –target

    Reply
  5. Chetan

    Hi
    I am unable to run phpdoc on ubuntu 11.04.
    When i run this then Iam faceing that type of error
    Parsing Files …

    PHP Version 5.3.5-1ubuntu7.3
    phpDocumentor version 1.4.3

    Parsing configuration file phpDocumentor.ini…
    (found in /var/www/PhpDocumentor/PhpDocumentor-1.4.3/)…

    done
    Maximum memory usage set at 828M after considering php.ini…
    using tokenizer Parser
    File /var/www/PhpDocumentor/PhpDocumentor-1.4.3/docbuilder Ignored

    ERROR: nothing parsed

    Reply
  6. Ahmed hassan

    The PHPDocumentor generate XML file named structure.xml and so css fils and js files
    how to configure it to generate html file like your pic

    Thanks

    Reply

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.