42

インスタンスの状態を変更しない関数の場合、メソッドの javadoc コメントは、多くの場合、Java-API の @return-tag のコメントと同じか、非常に似ています。

boolean Collection.isEmpty()

  • このコレクションに要素が含まれていない場合は true を返します。
  • このコレクションに要素が含まれていない場合は true

今、同じ問題を抱えている getExpression() のような多くの単純なメソッドの javadoc を書いています。API のように行うべきですか、それとも省略すべきですか?

4

4 に答える 4

30

オラクルの推奨事項Javadoc ツールのドキュメントコメントの書き方 から:

@return (参考ページ)

void を返すメソッドとコンストラクターの @return を省略します。その内容がメソッドの説明と完全に重複している場合でも、他のすべてのメソッドに含めます。明示的な @return タグを使用すると、だれかが戻り値をすばやく見つけやすくなります。可能な限り、特殊なケース (範囲外の引数が指定されたときに返される値を指定するなど) の戻り値を指定します。

于 2012-04-10T12:01:43.953 に答える
9

16では、「単純な状況での戻り情報の重複を避ける」ために、新しいコンボタグjavadocを使用できます。{@return ...}

/**
 * {@return the name of the object}
 */
public String getName();

(まだサポートされている) スタイルと同等です:

/**
 * Returns the name of the object.
 *
 * @return the name of the object
 */
public String getName();

詳細については、https://bugs.openjdk.java.net/browse/JDK-8075778を参照してください。

于 2021-02-16T08:02:03.530 に答える