php - phpdoc2 で php ファイルを文書化するためのガイドライン

Question

初めて phpdoc2 を使用してプロジェクトの文書化を開始すると、いくつかの質問に出くわしました。phpdoc.org のガイドを読みました。

phpdoc2 を使用する際に文書化するガイドラインはありますか? すべての変数を文書化する必要がありますか、それとも特定のスコープ/可視性の変数だけを文書化する必要がありますか?

私が今理解しているように、あなたはそれぞれを文書化します：

• ファイル
• クラス
• 関数

それでも… どこまでタグを使ってるの？

Answer 1

ドキュメントは、最も重要なことをすべてカバーする必要があります。可能であれば、例、外部リンクなどを提供することもできます。私は doxygen ソフトウェアを使用していますが、非常に優れていると思います。これにはこれらの機能があります。

php.net のマニュアルは非常に優れています。すべての関数、クラス、メソッドだけでなく、要件、導入などもカバーしています。

私にとって最悪の問題は、すべての詳細を文書化し、ある瞬間に「これにはうんざりだ」と言って、最も重要な部分の文書化やコメントをやめることです. 「私は覚えています」。

不足しているものを埋めるよりも、長すぎるものや冗長なものを削除する方が、1か月または1年後には常に簡単です。

あなたのポイントを見つけてください。