請求參數和PHPDoc的

可能重複：
Is there a standard for documenting GET/POST parameters?請求參數和PHPDoc的

試圖找出通過PHPDoc的的方式，有意義的文檔請求參數的最佳方式。具體來說，我有一些通過GET/POST接收參數的Zend Framework控制器操作，但不是功能參數。這有意義嗎？

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

如果我生成的文檔對於該方法，就不會出現的指示「命令」和「DIR」可以經由URL字符串該方法被傳遞。它會更有意義嗎？

@param string $order

我應該使用@var嗎？

思想歡迎。

來源

2009-08-12 typeoneerror

非常困惑，爲什麼我在「重複」之前一年問了這個問題，而我的關閉了。沒有意義。 – typeoneerror 2011-05-27 16:46:03

好問題，在Kohana回答這個問題3.謝謝你的觀點：] – Brenden 2012-01-17 20:03:32

我會避免使用@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); 
}

來源

2009-08-12 22:49:58

不錯！我喜歡驗證的想法。 – typeoneerror 2009-08-12 22:52:51

我通常要麼使用你的建議，要麼當代碼太長，或者什麼都不做時，使用簡單的非phpdoc註釋。

在這三者之間，我相信您的解決方案是最好的。

只有一件事你應該檢查：當你正在生成phpdoc時，這個渲染很好嗎？

從理論上講，作爲PHPDoc的使用您在文檔塊給的名字，我想這應該...

如果是......嗯，我沒有看到一個更好的辦法;不需要更好的方法：我認爲你可以做任何比這更乾淨/可讀/可理解的事情。

我不喜歡

@param string $order

的想法：沒有顯示$order應$_GET給予，而不是一個「真正的方法參數」;所以我寧願避免這種語法。

我不會以用戶爲@var參數，順便說一句：只爲變量，當我覺得他們記錄的需要（這是不是經常，至少在很短的代碼方法/件）

來源

2009-08-12 22:43:05

請求參數和PHPDoc的

回答

相關問題