Request params and phpdoc

Question

Trying to figure out the best way to document request parameters via phpdoc in a manner that makes sense. Specifically, I've got some Zend Framework controller actions that receive parameters via GET/POST, but aren't functional params. Does this make sense?

/**
 * Display a pagination/grid list of rows.
 *
 * @param string $_GET['order']  What field to sort on
 * @param string $_GET['dir']    Direction to sort; either ASC|DESC
 * 
 * @return void
 */
public function listAction()
{
    $order = $this->_request->order;
    ...

If I generated docs for this method, there wouldn't be an indication that "order" and "dir" can be passed via a url string to this method. Would it make more sense to just do

@param string $order

Should I use @var instead?

Thoughts welcome.

Answer 1

I generally either use what you proposed, or put a simple non-phpdoc comment when the code is too long, or just do nothing.

Between those three, your solution is the best, I believe.

Only one thing that you should check : does this render nicely when you are generating the phpdoc ?

In theory, as phpdoc uses the names you give in the doc-block, I suppose it should...

If yes... well, I don't see a better way ; not the need for a better way : I don't think you could do anything more clean/readable/understandable than this.

I do not like the

@param string $order

idea : nothing show the $order should be given in $_GET and is not a "real method parameter" ; so I'd rather avoid this syntax.

I never user @var for parameters, btw : only for variables, when I feel the need of documenting them (which is not often ; at least for short methods / parts of code)

Answer 2

I would avoid mucking with @param.

Also you could make a _validate() method to make it obvious in the code. Then you could use _validate() to create a seam for unit testing.

/**
 * Display a pagination/grid list of rows.
 *
 * Requires $_REQUEST['order'] and $_REQUEST['dir']
 * 
 * @return void
 */
public function listAction()
{
    list($order, $dir) = $this->_validate($this->_request);
    ...

private function _validate($request) {
    if (!$request->order)
         throw new InvalidArgumentException('"Order" must be in request');

    if (!$request->dir)
         throw new InvalidArgumentException('"Dir" must be in request');

    // maybe clean vars???
    //Zend_Filter_Numeric.....

    return array($request->order, $request->dir);
}