web-dev-qa-db-ja.com

プロパティのJavadocを書く方法は？

プロパティとゲッターとセッター（DTOスタイル）のみを保持する「単純な」POJOクラスのプロパティ/メンバーのjavadocを書くとき、私はしばしばジレンマに陥ります。

1）プロパティのjavadocを記述します
または...
2）ゲッターのjavadocを作成します

プロパティのjavadocを記述した場合、後でコード補完を介してPOJOにアクセスすると、IDE（Eclipse）は（当然）これを表示できません。そして、標準のjavadocタグはありません。 getter-javadocを実際のプロパティjavadocにリンクさせます。

例：

public class SomeDomainClass {

  /**
   * The name of bla bla bla
   */
  private String name;

  /**
   * @return INSERT SOME SMART JAVADOC TAG LINKING TO name's javadoc
   */
  public String getName() {  
    return name;  
  }

したがって、基本的に、Eclipse IDE getterのjavadocプロパティの説明を表示するために、javadocコメントを複製することなく他の人がどのように動作するかを聞くのは興味深いでしょう。

今のところ、プロパティではなくゲッターのみを文書化するように練習することを検討しています。しかし、それは最良の解決策ではないようです...

javajavadoc
86
user274360

Javadocsの生成中に（-privateを使用して）プライベートメンバーを含め、@ linkを使用してそのフィールドプロパティにリンクできます。

public class SomeDomainClass {
    /**
     * The name of bla bla bla
     */
    private String name;

    /**
     * {@link SomeDomainClass#name}
     */
    public String getName() {
        return name;
    }
}

あるいは、すべてのプライベートメンバーのJavadocを生成したくない場合は、すべてのゲッターを文書化し、セッターで@linkを使用する規則を設定できます。

public class SomeDomainClass {
    private String name;

    /**
     * The name of bla bla bla
     */
    public String getName() {
        return name;
    }

    /**
     * {@link SomeDomainClass#getName}
     */
    public void setName(String name) {
        this.name = name;
    }
}
71
Chandra Sekar

Eclipseのオートコンプリートの助けを借りて、両方を行います。

まず、プロパティを文書化します。

/**
 * The {@link String} instance representing something.
 */
private String someString;

次に、これをコピーしてゲッターに貼り付けます。

/**
 * The {@link String} instance representing something.
 */
public String getSomeString() {
    return someString;
}

Eclipseでは、@ returnステートメントにオートコンプリートがあります。そのため、Word Getsを追加し、「t」を小文字にして、小文字の「t」で文をコピーします。次に、@ return（Eclipseオートコンプリートを使用）を使用し、文を貼り付けてから、戻り値でTを大文字にします。それは次のようになります：

/**
 * Gets the {@link String} instance representing something.
 * @return The {@link String} instance representing something.
 */
public String getSomeString() {
    return someString;
}

最後に、そのドキュメントをセッターにコピーします。

/**
 * Gets the {@link String} instance representing something.
 * @return The {@link String} instance representing something.
 */
public void setSomeString(String someString) {
    this.someString = someString;
}

次に、それを変更し、Eclipseオートコンプリートを使用すると、@ paramタグだけでなくパラメーターの名前も取得できます。

/**
 * Sets the {@link String} instance representing something.
 * @param someString The {@link String} instance representing something.
 */
public void setSomeString(String someString) {
    this.someString = someString;
}

これで完了です。私の意見では、このテンプレートは、長い目で見れば、繰り返しによってプロパティの意味を思い出させるだけでなく、サイドを追加したい場合はゲッターとセッターに追加のコメントを追加するのが簡単になります効果（nullプロパティを許可しない、文字列を大文字に変換するなど）。この目的でEclipseプラグインを作成することを検討しましたが、JDTに適した拡張ポイントが見つからなかったため、あきらめました。

文は常にTで始まるとは限らないことに注意してください。これは、貼り付けの際に最初の文字を大文字/小文字に変換する必要があるだけです。

3
MetroidFan2002

Lombok は、このようなタスクに非常に便利なライブラリです。

@Getter
@Setter
public class Example {
    /**
     * The account identifier (i.e. phone number, user name or email) to be identified for the account you're
     * requesting the name for
     */
    private String name;
}

必要なのはそれだけです！ @Getterアノテーションは、各プライベートフィールドにgetterメソッドを作成し、javadocをそれに添付します。

[〜＃〜] ps [〜＃〜]：ライブラリには、チェックアウトしたいクールな機能がたくさんあります

2
Amanuel Nega

私は本当にそれが問題だと思うし、公式の Javadocガイド はそれについて何も語っていない。 C＃は、Propertiesを使用してこれをエレガントな方法で解決できます（私はC＃でコーディングしませんが、本当に素晴らしい機能だと思います）。

しかし、私には推測があります：someStringが何であるかを説明する必要がある場合、それはあなたのコードについての「悪い小さな」かもしれません。つまり、someStringを入力してSomeClassを記述する必要があるため、SomeClassのドキュメントでsomeStringとは何かを説明します。したがって、getter/setterのjavadocは必要ありません。

0
Leonardo Leite