Writing good php docs
By Justin Silverton
Documentation is a very important part of development. It will not only allow you to come back to an application or piece of code in the future with ease, but also help future coders (in the open source community or at your job, etc) that may be utilizing your source code.
A great tool that can be used for this is called phpDocumentor (or phpdoc) available here.
Features
- output in HTML, PDF (directly), CHM (with windows help compiler), XML DocBook
- web and command-line interface
- fully customizable output with Smarty-based templates
- recognizes JavaDoc-style documentation with special tags customized for PHP 4
- generates a todo list from @todo tags in source
Installation
There are two different ways to install this. The first is to download the source directly and install it manually (found here). The second is to install it through the pear library. This can be done using the following command: “pear install PhpDocumentor”
To install phpDocumentor to use the web interface, you must first change one of PEAR’s configuration variables, data_dir, to be a sub-directory of your web server’s document root. The simplest way to do this is through PEAR’s command-line interface with the command: pear config-set data_dir /path/to/document_root/pear
Configuring this value through the web interface is also simple. Click on the configuration icon in the left-hand frame, and type in the path in the data_dir text box.
Usage
It’s fairly easy to start documenting your code. There are sample projects included that show some common usage (sample1.php, sample2.php, and sample3.php).
If you are using the command-line interface, run this command from the tutorials/sample directory:
phpdoc -o HTML:frames:earthli -f sample1.php -t docs (replace sample1.php with the file you want to process)
The rest of the available options can be found using: phpdoc -h
Full Docs can be found here
1 Comment so far
Leave a reply
What’s really missing though is a simple way to apply the phpdoc comments to files. Example, in eclipse you can add missing javadoc comments to a java file by pressing “Alt + Shift + J”. You can use the brilliant Checkstyle plugin to validate code and enforce compliance with a predefined coding standard.
More of a limitation of PHPEclipse admittedly, that it cannot do this. But perhaps phpdoc should consider patterning with some open source editor to provide integrated phpdoc support. Remains to be seen if I am lazy enough to write a plugin, just so I can add comments easily.
Cool blog by the way:)