リクエストパラメータとはphpdoc

Question

可能性の重複：
Is there a standard for documenting GET/POST parameters?

は理にかなった方法では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を使用する必要がありますか？

歓迎します。

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

Answer 2

私は一般に提案したものを使用するか、コードが長すぎる場合は単純な非phpdocコメントを入力するか、何もしないでください。

これらの3つの間で、あなたのソリューションは最高です、私は信じています。

チェックする必要があるのは1つだけです。これは、phpdocを生成するときにうまくレンダリングされますか？ phpdocのは、あなたがDOC-ブロックに与える名前を使用して、私はそれが必要とし理論的には

、...

はい...よく、私はより良い方法が表示されない場合。より良い方法の必要性ではありません：私はあなたがこれ以上のきれいな/読解可能な何かを行うことができるとは思わない。

私は

@param string $order 

アイデアを好きではない：何も$orderが$_GETに与えられ、「実際のメソッドパラメータ」ではありませんする必要があります示していません。だから私はむしろこの構文を避けるだろう。

ところでパラメータのため、私は決してユーザー@var、

：変数だけのために、私は（多くの場合ではありません。少なくとも、コードの短い方法/パーツ用）、それらを文書化する必要性を感じる