请求参数和phpdoc

Question

可能的重复：
是否有文档化GET / POST参数的标准？

尝试找出以最合理方式通过phpdoc文档记录请求参数的方法。具体来说，我有一些Zend Framework控制器操作，它们通过GET / POST接收参数，但不是功能参数。这有意义吗？

/**
 * 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;
    ...

如果我为这个方法生成文档，将不会显示“order”和“dir”可以通过url字符串传递给该方法的指示。只是这样做是否更有意义？

@param string $order

我应该使用@var吗？

欢迎分享您的想法。

- typeoneerror

---

非常困惑，为什么我在一年前提出了这个问题，而“重复”的问题却被关闭了。毫无意义。 - typeoneerror

很好的问题，我在Kohana 3中自己回答了。感谢你的观点 :] - Brenden

Answer 1

我会避免对 @param 进行操作。

同时，你可以创建一个 _validate() 方法来使代码更加明显。然后，你可以使用 _validate() 来为单元测试创建一个接口。

/**
 * 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);
} 

- Lance Rushing

---

不错！我喜欢验证的想法。 - typeoneerror

Answer 2

通常我会使用你提出的方法，或者在代码太长时放一个简单的非phpdoc注释，或者什么都不做。

在这三种方法中，我相信你的解决方案是最好的。

只有一件事情需要检查：当你生成phpdoc时，它是否能够很好地呈现？

理论上，由于phpdoc使用你在文档块中给出的名称，我想应该可以...

如果可以...那么，我没有看到更好的方法；也没有更好的方法的必要：我认为你无法做得比这更清晰/可读/易懂。

我不喜欢

@param string $order

想法：如果在$_GET中没有显示$order，并且它不是“真正的方法参数”，那么我宁愿避免使用这种语法。

顺便说一句，我从来不为参数使用@var：只为变量使用，当我感到有必要记录它们时（这并不经常发生；至少对于短的方法/代码部分）

- Pascal MARTIN