2017-08-08 1 views
1

私のクラスが外部ライブラリ(書かなかったもの)からよく書かれた外部インターフェイスを実装している場合、例えばAttributeConverterからjavax.persistenceまで、私はオーバーライドメソッドを文書化する正しい方法を考えています。 @inheritDocまたはjavadoc以外のコメントブロックを使用するのか、ドキュメントが簡単に見つかる可能性があるので、まったくドキュメント化していないのでしょうか?Javadocあなたがソースを書いたものではない外部インターフェイスを実装しているクラスですか?

答えて

2

これは実行しようとしている内容によって異なります。あなた自身に尋ねなければならない最初の質問は次のとおりです。親Javadocに追加するものはありますか?

答えが「いいえ」の場合、これは意見に基づくものです。あなたがちょうどそれを残しておけば、@Overrideを使う限り、Javadocの親が使用されます。その結果はnon-javadocのコメントが不必要になります。それはまだソースコードの目的を果たしています。 Should I use a "non-Javadoc" comment?

@inheritDocは、使用されている要素のみをコピーするので、この場合は役に立ちません。 documentationから:

法主説明または@return、@paramまたは@throwsタグコメントにインラインタグ{@inheritDoc}を挿入 - 対応継承主説明またはタグコメントはその場所にコピーされます。

親のドキュメントに何かを追加したい場合は、これが有効です。あなた自身のコメントのある時点で親文書を挿入するために使用します。

関連する問題