Question

可能重复：
Is there a standard for documenting GET/POST parameters?

尝试找出以有意义的方式通过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吗？

欢迎思考。

Answer 1

我会避免与@param混在一起。

此外，您可以创建一个_validate（）方法，使其在代码中显而易见。然后，您可以使用_validate（）为单元测试创建 seam 。

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

Answer 2

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

在这三者之间，我相信你的解决方案是最好的。

你应该检查的只有一件事：当你生成phpdoc时，这会很好地呈现吗？

理论上，由于phpdoc使用你在doc-block中给出的名字，我想它应该......

如果是的话......好吧，我看不到更好的方法;不需要更好的方法：我认为你不能做比这更干净/可读/可理解的事情。

我不喜欢

@param string $order

想法：没有任何内容显示$order应该在$_GET中给出，而不是“真正的方法参数”;所以我宁愿避免这种语法。

我从来没有使用@var来获取参数，顺便说一下：只有变量，当我觉得需要记录它们时（这种情况并不常见;至少对于简短的方法/部分代码而言）

请求参数和phpdoc

2 个答案: