良いjavadocコメントを書く方法は？
私はJava開発者です。私が書いたコードとプログラムのJavadocコメントの品質を改善して、他の開発者がより理解しやすく、簡単に実装できるようにすることに興味があります。
私は公式の情報源からのものを含む多くの記事を読みました、そして私は本に述べられたガイドラインに従おうとします "The Elements of Java Style" 、しかしそれにもかかわらず、オンラインで広範囲に検索した後、既存のJavadocをモデルの例と比較し、Java APIドキュメントのベストプラクティスを維持するための実用的な方法を見つけることができないようです。
ピアレビュー。
チーム外の誰か（顧客）を探して、JavaDocについてどう思うか尋ねてください。
顧客は常に正しいです。
また、私はあなたにいくつかのものを共有することができます
Javadocの作成に関する優れた記事は、Sunのサイト http://www.Oracle.com/technetwork/Java/javase/documentation/index-137868.html にあります。
そのテキストから私が学んだ最も良いことは、おそらくクラスレベルのjavadocは「Provides」で始まる必要があるということです。これにより、そのクラスがプログラム（または世界）に何を提供するかを考える必要があります。 javadocを書くことで「ねえ、これはここでは必要ない！」と思ったので、ソフトウェアを再設計することは珍しくありません。
その他の実用的なヒント：ゲッターが興味深い場合は、@ returnsタグに書き込んでみてください。そうしないと、javadocに1回、@ returnタグの後に1回、計2回入力することになります。
最良のヒント：何を書くべきかわからない場合は、しないでください。 Javadocパーサーは、たとえばgetter javadocを自動的に生成するという優れた機能を果たしますが、/ ** * /を追加しなかった場合にのみ実行されます。
Javadocは、メソッドの機能ではなく、メソッドの機能を説明する必要があります。
Javadocはあなたのtodolistではありません。私はそれを試しましたが、より大きなプロジェクトの場合、それは単に機能しません。
http://www.Oracle.com/technetwork/Java/javase/documentation/index-137868.html にあるSun（現在のOracle）のドキュメントに加えて、「 アイテム44：公開されているすべてのAPI要素のドキュメントを作成する "Joshua Bloch、第2版の「EffectiveJava」ブックから。 pp.203-208。これは、いくつかの実用的な例を含む6ページの推奨事項/ヒントです。
'VoucherStore'には@linkパラメータを使用できます
例：
@return {@link VoucherStore} type Concrete Object based on storeType parameter
の代わりに
@return returns VoucherStore type Concrete Object based on storeType parameter.
より良い方法は、作成したサンプルメソッドを投稿することです。そうすれば、そのためのJavadocの作成を支援できます。あなたが一般的な提案を求めているだけなら、その本をしのぐのは難しいかもしれません。