DRYオーバーロードメソッドでJavadocを作成する方法
DRY=の方法でJavadocを書きたいのですが、 Javadoc に関するOracleのドキュメントでは、オーバーロードメソッドのコメントに同じことをもう一度書くと書いてあります。繰り返しは避けられませんか？
ふりかける{@inheritDoc}ディレクティブは、スーパークラスのメソッドをオーバーライドしたり、インターフェース定義のメソッドを実装したりするときに、Javadocコメントのあちこちにあります。
これは少なくとも私にとってはうまく機能し、ソースコードでの繰り返しを回避します。必要に応じて、特定の情報を特定のJavadocコメントに追加することもできます。まともなIDEが関連付けられた識別子名にカーソルを合わせてレンダリングされたJavadocを取得することである場合、Javadocコメント自体が問題になることはほとんどありません。参考文献とすべて。
ドキュメント化のポイントは、アイテムの将来のユーザーを明らかにすることです。これは部分的には作者の便宜のためであり、そのため、誰かがその仕組みを理解できないときはいつでも連絡を取る必要はありません。ただし、ほとんどの場合、それを使用またはサポートする必要がある人々の利益のためです。
そのため、著者にとっての便宜とは対照的に、ポイントは明快でなければなりません。あなたは本質的に怠惰で自分自身を繰り返すことができなかったので、人々がAPIドキュメントを探し回るのを期待することはできません。それを吸ってください-Javadocは繰り返しになります。
そうは言っても、理由はありません。賢いのであれば、マーカーやその他の基準に基づいてコードにコメントを貼り付けるプログラムを作成することはできません。それは価値があるよりももっと面倒かもしれません。か否か。