0

PHPDocumentor2 を使用して PHP プロジェクトの文書化を行っています。皮肉なことに、PHPDoc のドキュメントはあまり詳しくありません。ファイル、クラス、関数、および変数にコメントを付ける方法を完全に理解していますが、変数または定数が if ステートメント内で定義されている場合、どのようにコメントすればよいですか?

例：

if ($foo==$bar) {
    define('FOOBAR',$foo);
} else if ($foo>$bar) {
    define('FOOBAR',$bar);
} else {
    define('FOOBAR',$foo+$bar);
}

明らかに、私は 3 つのコメントを追加したくありません。また、ドキュメンテーションは if ステートメントを論理的に説明する必要があるため、if ステートメントの開始前に docBlock を配置する必要があります。 「define」の直前の行にある必要があります。最初のものの前に置くことができますが、奇妙に見えます。

if ($foo==$bar) {
    /**
     * FOOBAR Definition.
     *
     * Value of FOOBAR. Yada yada.
     * @var int
     */
    define('FOOBAR',$foo);
} else if ($foo>$bar) {
    define('FOOBAR',$bar);
} else {
    define('FOOBAR',$foo+$bar);
}

何か案は？

4

1 に答える 1

0

phpdoc2の@ignore動作に対する期待は、phpdoc1の期待とは異なる可能性があります。

phpdoc1では、@ignoreタグは事実上「ドキュメント化可能な要素を含む次のコードが表示されますか？そのコードを無視してください」という意味です。この動作により、PandyLegendの例は、上記のcode+docblocksとまったく同じように機能するようになりました。マニュアルの@ignoreの使用例は、実際にはPandyLegendの使用例とも一致します（http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.ignore.pkg.html）。

PandyLegendの例を使用して見たphpdoc2の動作から判断すると、phpdoc2は、「この次のコードにドキュメント化可能な要素が表示されますか？その名前を記録し、このドキュメントセット全体でその要素を完全に無視する」と考えていると思います。

私の推測では、この問題は実際にはバグではなく、単なる別の解釈です。

（https://github.com/phpDocumentor/phpDocumentor2/issues/583）

于 2012-08-29T14:34:52.540 に答える