Writing document for PHP code
Since last night I start to consider writing more complete documentation inside the plugin itself. Of course it’s just API documentation, which is NOT a replacement of how to use the plugin. (Hey, I know, I know, this plugin has no public API, it is just for converting posts and comments, and not intended to be used for themes and templates)
The immediate solution found by googling is phpDocumentor. Not a very brilliant solution, but enough to get the job done, especially good because it parses PHP files quickly and is easy to learn. For example:
/**
* Error constant used when content is known to be invalid or dangerous.
*
* Dangerous content means special constructs causing
* inclusion of another file or command execution, etc.
*/
define('ERR_INVALID_INPUT', -1);
/**
* Generate HTML content from error message or rendered image
* @param string $input Music fragment to be rendered
* @param object $render PHP object created for rendering relevant music fragment
* @return string $html The HTML content
*/
function scorerender_process_content ($input, $render)
{
phpDocumentor has a quick start guide on how to install itself through Pear. After getting the doc done, the hardest part is over; generating document is relatively easy. Just a single command:
phpdoc -o HTML:frames:earthli -f *.php -t docs
And voila! Documents are readily available under docs/ directory for your browsing pleasure. Generally this step just takes a few seconds for small project with several small PHP files. What does it look like? See the pic on the right.