10

PHPDoc のドキュメントを調べていたところ、さまざまなメソッドに送信していた Post 変数をドキュメント化する適切な方法が見つかりませんでした。

そこで、これらすべての変数を文書化するためのより良い方法を提供してくれることを期待して、Doxygen の調査を開始しました。私のコードには多くの AJAX リクエストが含まれているため、ほとんどの変数はポスト経由で送信されます。

ポスト変数を dox​​ygen で文書化する良い方法はありますか? 標準のパラメータ タグで実行しただけでエラーが発生するかどうかを判断するのに苦労しています。

そうでない場合、このプロセスに役立つ可能性のある別のドキュメンターはありますか? それとも、手動ですべてを文書化して、自動文書化ツールを探すのを無視するべきですか?

ありがとう！

4

1 に答える 1

8

メソッドがメソッド引数としてではなく、$ _ POSTから直接それらを読み取る場合は、メソッドのdocblockの@usesタグを使用します。

/**
 * My foo() method
 * @return void
 * @uses $_POST['bar'] directly
 */
public function foo()
{
    echo "I use ", $_POST['bar'], "... :-)";
}

別のオプションは@globalタグかもしれません：

/**
 * My bar() method
 * @return void
 * @global mixed uses the 'bar' key from the $_POST superglobal directly
 */
public function foo()
{
    global $_POST;
    echo "I use ", $_POST['bar'], "... :-)";
}

「global」キーワードは、メソッド内のスーパーグローバルには技術的に必要ではないことを認識していますが、それを文書化するのに役立ちます。

編集

PHPDocのリファレンスガイドによると、@usesは双方向の関係を示すことを目的としていることに注意してください。

ドキュメントジェネレータは、@usesタグに関連付けられた要素にリンクする受信要素のドキュメントに@used-byタグを作成する必要があります

したがって、意味的には@usesの方が読みやすいかもしれませんが、@seeを使用して$_ [POST | GET|REQUEST]パラメーターを文書化することもできます。2つの主な/唯一の違いは、 @ seeは、docブロックで参照されているFQSENへの一方向のリンクであることを意味していることです。

于 2012-08-03T19:24:11.313 に答える