7

API ドキュメントのために Java でコンストラクターの param タグと return タグを記述する必要がありますか?

これは私が持っているコードです:

/**
* Another constructor for class Time1
*/
public Time1 (Time1 other) 
    {
        _hour = other._hour; _minute = other._minute; _second = other._second;
    }
4

2 に答える 2

8

を作成する全体的な目的はDocumentation、実装者がコードで何をしようとしているのかを理解できるようにすることです。

  • すべてのために作成する必要がありますdocumentationか? yes あなたの使用を計画しているプログラマーAPIは、a の「明白な」目的を理解してmethod,property,constructor,classいない可能性があります。

使用は@param, @return annotations、この場合にのみ使用する必要があります。質問コードの例では、次のようになります。

/**
* Another constructor for class Time1
*/ public Time1 (Time1 other) 
    {
        _hour = other._hour; _minute = other._minute; _second = other._second;
    }

それで、あなたのコンストラクターは何かを返しますか? いいえ、なぜ@return注釈を使用するのですか。しかし、あなた constructor が持っているのはパラメーターなので、ここで行う正しいことは次のようになります。

/**
* Another constructor for class Time1
* @param other  <and explain its purpose>
*/
public Time1 (Time1 other) 
    {
        _hour = other._hour; _minute = other._minute; _second = other._second;
    }
于 2015-12-27T16:55:48.250 に答える
3

コンストラクターに return タグを含めることは意味がありませんが、それ以外は、コンストラクター Javadoc はメソッドの Javadoc と似ています。特定のタグを含める必要はありませんが、さまざまな理由で含めることを選択できます。おそらく、特定のパラメーターに関するポイントを説明するため、特定の例外がスローされる可能性のある条件を強調するため、またはいくつかの条件に準拠するためだけに-ハウスコーディングのガイドライン。

一般に、有用な情報だけを Javadoc に含めることをお勧めします。のようなものAnother constructor for class Time1は特に役に立ちません-そのコンストラクターが別のコンストラクターで使用される理由や、このコンストラクターが存在する理由については説明していません。

于 2015-12-27T16:57:51.930 に答える