Describing PHP functions efficiently

Question

How can you describe the parameters and return type (getter/setter) of your PHP functions?

I need to tell my moderator the return type and list the parameters for each function. I have hundreds of functions so this is becoming problem, since I need to do this for every single revision.

I use at the moment the following procedure

1. ack-grep "function " > /tmp/functions 2 . in Vim:
   
   • %s/\d//g, %s/{//, %s/://g
   • `%s/.*.php/\U&/
   • then putting the Uppercase filename to the beginning of the list of functions of each file
   • put functions to one file and the parameters to another file such that the linenumbers match
   • create a third file where you write either setter or getter for the corresponding line
2. paste -d"&" /tmp/{functions,functions_param,functions_type}
3. add LaTeX formatting to each set of functions of each file

Answer 1

Use something like phpdoc.

Basically you add special comments to your code:

/**
 * A sample function docblock
 * @global string document the fact that this function uses $_myvar
 * @staticvar integer $staticvar this is actually what is returned
 * @param string $param1 name to declare
 * @param string $param2 value of the name
 * @return integer 
 */
function firstFunc($param1, $param2 = 'optional') {
    static $staticvar = 7;
    global $_myvar;

    return $staticvar;
}

and it automatically generates HTML documentation for it.

Basically the idea behind this is to make a programmer's life easier, and allow writing in-line API documentation without having to spend a lot of time at it.

There are some IDEs that also understand this, and will show the documentation while you are using it. For example, the function:

/** Retrieve the action key
 * @return string
 */
function isValid($value) {
  ....
}

Shows this in Zend studio: http://static.zend.com/topics/code-assist.png

Especially if you're using an IDE like this (there are others besides Zend that do it), you'll likely find yourself naturally documenting every function and parameter, because it helps you while you're coding anyways.

Answer 2

phpdoc. Taking the the sum function that adds two numbers and returns the result as an example:

/**
 * Adds up two int numbers
 * @param int $x the first number to add
 * @param int $y the second number to add
 * @return int the result of the operation
 */
 function my_sum ($x, $y)
 {
     return $x+$y;
 }