だけで何か

Question

私はいくつかのjavadocを（実際には、彼らはjsdocsがあるが、それはこの質問のために違いはありません）、この繰り返しパターン発見書いを返すメソッドを文書化：

だけで返すメソッドを想像します値、多分計算の産物。たとえば、Unixエポックからの経過時間をミリ秒単位で表します。

public long getTimeSinceTheEpoch(){ 

    //calculate time 

    return time; 
} 

これまでのところ、とても良いです。時間はjavadocを追加するために来るとき今（またはjsdocs、またはrdocsを、何でも）、私はこのような何か書いてきた。ここで

/** 
* Gets the time in milliseconds since the unix epoch 
* 
* @returns the time in milliseconds since the unix epoch 
*/ 
public long getTimeSinceTheEpoch(){ 

を、問題が明らかです。

私の質問は、コメントの本文に何を入れますか？コメントの属性にはどのようなものがありますか？

重要

私はそれが私に依存している場合、私はgetTimeInMillisecondsSinceTheEpochのようなものにする方法を名前を変更し、全くのコメントを避けるだろう、コメントのこれらの種類のファンではありません。

私はそれをすることはできません（コメントを避ける）ので、私はできるだけそれらを有用にするよう努力しています。

Answer 1

（現在オラクル）スタイルガイド「How to Write Doc Comments for the Javadoc Tool」Sunはこのことをお勧めします。

@returnタグは、それが持つ冗長 であったとしても、無効以外 他の何かを返すすべての 方法のために必要ですメソッドの説明。 （たび 可能、 用タグコメントを使用するための非冗長 （理想的には、より具体的な何かを）見つける。）

私は冗長性が好きではないよ、それはDRY原則に反します。個人的には、私はサマリーを1つ作成し、もう1つはディテール（上に示唆したように）を作成するか、または@returnだけを提供します。あなたが指摘しているように、単純なゲッターの名前で要約としても十分です。

Answer 2

あなたが返すものを確実に文書化する必要がある場合は、@returnの説明だけを提供することをお勧めします。

コメント欄で同じ1行をスローすることもできますが、を追加することもできます。返すものを返す方法については、

/** 
* Gets the time in milliseconds since the unix epoch 
* by doing something incredible. 
* http://stackoverflow.com/questions/4307142/documenting-a-method-that-just-returns-something 
* 
* @note thank you stackoverflow 
* 
* @returns the time in milliseconds since the unix epoch 
*/ 
public long getTimeSinceTheEpoch(){