Wie schreibe ich Javadoc von Eigenschaften?

Ich habe oft ein Dilemma, wenn ich Javadoc für Eigenschaften / Mitglieder einer "einfachen" POJO-Klasse schreibe, die nur Eigenschaften und Getter und Setter enthält (DTO-Stil) ....

1) Schreiben Sie Javadoc für die Eigenschaft
oder ...
2) Schreiben Sie Javadoc für den Getter

Wenn ich Javadoc für die Eigenschaft schreibe, kann meine IDE (Eclipse) dies (natürlich) nicht anzeigen, wenn ich später über die Code-Vervollständigung auf das POJO zugreife. Und es gibt kein Standard-Javadoc-Tag, mit dem ich das Getter-Javadoc mit der eigentlichen Eigenschaft Javadoc verknüpfen kann.

Ein Beispiel:

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

Grundsätzlich wäre es also interessant zu hören, wie andere vorgehen, damit Ihre Eclipse-IDE die Beschreibung der Javadoc-Eigenschaften für Ihre Getter anzeigt - ohne den Javadoc-Kommentar duplizieren zu müssen.

Ab sofort denke ich darüber nach, in meiner Praxis nur die Getter und nicht die Eigenschaften zu dokumentieren. Aber es scheint nicht die beste Lösung zu sein ...

Sie können private Mitglieder beim Generieren von Javadocs (mit -private) einbeziehen und dann mit @link auf diese Feldeigenschaft verlinken.

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

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

Wenn Sie das Javadoc nicht für alle privaten Mitglieder generieren möchten, können Sie alternativ eine Konvention festlegen, um alle Getter zu dokumentieren und @link für Setter zu verwenden.

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

Lombok ist eine sehr praktische Bibliothek für solche Aufgaben.

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

Das ist alles was du brauchst! Die @GetterAnnotation erstellt eine Getter-Methode für jedes private Feld und hängt das Javadoc daran an.

PS : Die Bibliothek hat viele coole Funktionen, die Sie vielleicht auschecken möchten

Ich mache beides, unterstützt von Eclipse's Autocomplete.

Zuerst dokumentiere ich die Eigenschaft:

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

Dann kopiere ich dies und füge es in den Getter ein:

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

Bei Eclipse haben @ return-Anweisungen eine automatische Vervollständigung. Daher füge ich das Wort Gets hinzu, schreibe das "t" in Kleinbuchstaben und kopiere den Satz mit dem Kleinbuchstaben "t". Ich benutze dann @return (mit Eclipse Autocomplete), füge den Satz ein und schreibe dann das T in der Rückgabe in Großbuchstaben. Es sieht dann so aus:

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

Schließlich kopiere ich diese Dokumentation in den Setter:

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

Dann ändere ich es und mit Eclipse Autocomplete können Sie nicht nur das @ param-Tag, sondern auch den Namen des Parameters erhalten:

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

Dann bin ich fertig. Meiner Meinung nach macht es dieses Templating auf lange Sicht viel einfacher, sich nicht nur durch Wiederholung daran zu erinnern, was die Eigenschaft bedeutet, sondern es macht es auch einfacher, dem Getter und Setter zusätzliche Kommentare hinzuzufügen, wenn Sie eine Seite hinzufügen möchten Effekte (z. B. keine Null-Eigenschaften zulassen, Zeichenfolgen in Großbuchstaben umwandeln usw.). Ich habe untersucht, wie ich ein Eclipse-Plugin für diesen Zweck erstellen kann, aber ich konnte keinen geeigneten Erweiterungspunkt für das JDT finden, also habe ich aufgegeben.

Beachten Sie, dass der Satz möglicherweise nicht immer mit einem T beginnt - es ist nur der erste Buchstabe, der beim Einfügen nicht kapitalisiert / rekapitalisiert werden muss.

Ich denke wirklich, dass es ein Problem ist und der offizielle Javadoc-Leitfaden sagt nichts darüber aus. C # kann dies auf elegante Weise mit der Verwendung von Eigenschaften lösen (ich codiere nicht in C #, aber ich denke wirklich, dass es eine nette Funktion ist).

Aber ich habe eine Vermutung: Wenn Sie erklären müssen, was someString ist, ist es vielleicht ein "schlechtes kleines" an Ihrem Code. Es kann bedeuten, dass Sie SomeClass schreiben sollten, um someString einzugeben, damit Sie erklären, was someString in der SomeClass-Dokumentation ist, und nur damit die Javadocs in getter / setter nicht erforderlich sind.