parameters – Describing PHP functions efficiently

parameters – Describing PHP functions efficiently

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 programmers 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 youre using an IDE like this (there are others besides Zend that do it), youll likely find yourself naturally documenting every function and parameter, because it helps you while youre coding anyways.

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;
 }

parameters – Describing PHP functions efficiently

Leave a Reply

Your email address will not be published.