6

重複の可能性:
GET/POST パラメーターを文書化するための標準はありますか?

理にかなった方法で 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;
    ...

このメソッドのドキュメントを生成した場合、URL 文字列を介してこのメ​​ソッドに「order」と「dir」を渡すことができるという兆候はありません。するだけのほうが理にかなっていますか

@param string $order

代わりに @var を使用する必要がありますか?

考えは大歓迎です。

4

2 に答える 2

6

@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-12T22:49:58.727 に答える
1

私は通常、あなたが提案したものを使用するか、コードが長すぎる場合は単純な非 phpdoc コメントを入れるか、何もしません。

これら 3 つの中で、あなたのソリューションが最適だと思います。


確認すべきことは 1 つだけです。これは、phpdoc を生成しているときに適切にレンダリングされますか?

理論的には、phpdoc は doc-block で指定した名前を使用するため、そうすべきだと思います...

はいの場合...まあ、もっと良い方法はありません。より良い方法の必要性ではありません：これよりもクリーン/読みやすく/理解しやすいことはできないと思います。


私は好きではありません

@param string $order

アイデア :$orderで指定する必要があることを示すものは何も$_GETなく、「実際のメソッド パラメータ」ではありません。したがって、この構文は避けたいと思います。


パラメータに@varを使用することはありません.btw：変数についてのみ、それらを文書化する必要があると感じた場合（これは頻繁ではありません;少なくとも短いメソッド/コードの一部の場合）

于 2009-08-12T22:43:05.680 に答える