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:
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
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.
Follow Me:
How to get phpDocumentor to work with PHP5.3 namespaces?
Hi Glen,
I don think it’s a problem but nevertheless I would ask your permission to put your link http://www.glenscott.co.uk/2009/02/18/phpdocumentor-in-5-minutes/ as a reference on my web page concerning the use of PhPDocumentor. You did me remember the installation procedure for phpdocumentor via PEAR 😉 So thanks 😉
Yours,
Frederik in Brussels
No problem Frederik, I’m glad you found the tutorial useful!
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
@Bill Hernandez
Try using the long options instead:
phpdoc –file Accumulator.php –target /projects/a/project_00015/docs/
Do you get the same error?
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
Hi Arun,
Try using the long options instead:
phpdoc –file Accumulator.php –target /projects/a/project_00015/docs/
Do you get the same error?
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
I’m getting the same error as @Bill and @Arun
If this helps anyone, found a win based solution at: http://stackoverflow.com/questions/4723781/phpdocumentor-on-legacy-code
I’m using a debian system but will post my solution later… if I find one
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
Hi
Glen i am any response form your side till now.
Hi Chetan,
What is the exact phpdoc command that you are running?
-Glen
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
How do I document functions which are not in a class? have a file with many functions which i include in other files.