Whenever I write a class in PHP, I like to put a list of public functions at the top of the class like this:
// add_project($apikey, $post, $email)
// create_user($apikey, $email, $firstname, $lastname, $rolename, $pid)
// user_join_project($apikey, $email, $pid)
I was wondering if there were any tools that can automate this process. Like perhaps I could load the class file and it could generate a list of the function names, variables and such?
Thanks!
Try phpDocumentor. You use DocBlock syntax for comments (similar to Javadoc and in other languages) then pass your PHP source files through the phpDocumentor parser, and it generates API documentation for you.
A rough example:
/**
* Adds a project.
*
* @param string $apikey The API key.
* @param object $post The post.
* @param string $email A supplied email address.
* @return void
*/
function add_project($apikey, $post, $email) {
...
}
There's a not great deal of value in this approach.
First off, if you're not already doing so you should mark each of your methods (and indeed member variables) with the appropriate visibility (public/protected/private). You could then use a solution such as phpDoc, which to properly document each method argument in addition to providing an overall purpose for each method/class, etc.
You can then automatically generate documentation for your project in HTML format (amongst others).
There are various tools for this. They are called PHP documentor's. I use an IDE called PHPStorm that has a documentor integrated.
This can be done pretty easily with Parsekit.
Using this ("tmp.php") as sample data:
<?php
class Fruit
{
public function apple($cored) {}
public function orange($peeled) {}
public function grape($colour, $seedless) {}
}
Here's a simple Parsekit example to dump a class's functions:
<?php
$parsed = parsekit_compile_file($argv[1]);
foreach ($parsed['class_table'] as $class => $classdat) {
foreach ($classdat['function_table'] as $func => $funcdat) {
echo "{$class}::{$func}(";
$first = true;
foreach ($funcdat['arg_info'] as $arg => $argdat) {
if (!$first) {
echo ', ';
}
echo "\${$argdat['name']}";
$first = false;
}
echo ")\n";
}
}
…and here it is in use:
$ php parse.php tmp.php
Fruit::grape($colour, $seedless)
Fruit::orange($peeled)
Fruit::apple($cored)
