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

Question 1

プロパティとゲッターとセッター（DTOスタイル）のみを保持する「単純な」POJOクラスのプロパティ/メンバーのjavadocを作成するときに、ジレンマに遭遇することがよくあります。

1）プロパティのjavadocを記述する
か...
2）ゲッターのjavadocを記述します

プロパティにjavadocを記述した場合、後でコード補完を介してPOJOにアクセスすると、IDE（Eclipse）は（当然）これを表示できません。また、getter-javadocを実際のプロパティ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コメントを複製する必要はありません。

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

Question 2

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

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;
    }
}

Question 3

ロンボクはそのようなタスクのための非常に便利なライブラリです。

@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注釈は、各プライベートフィールドの取得メソッドを作成し、Javadocを取り付けます。

PS：ライブラリには、チェックアウトしたい多くのクールな機能があります

Question 4

私は両方とも、Eclipseのオートコンプリートによって支援されています。

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

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

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

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

Eclipseでは、@ returnステートメントにオートコンプリートがあります。そのため、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で始まるとは限らないことに注意してください。これは、貼り付けの際に、大文字と小文字を区別する必要があります。

Question 5

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

しかし、私は推測しています：someStringが何であるかを説明する必要がある場合、それはおそらくあなたのコードについて「悪い小」です。someClassを記述してsomeStringを入力する必要があることを意味する場合があるので、SomeClassのドキュメントでsomeStringとは何かを説明し、ゲッター/セッターのjavadocsは必要ありません。