Wie schreibe ich Javadoc von Eigenschaften?

Question

ich mich oft mit einem Dilemma finden, wenn Objekte/Mitglieder einer „einfachen“ POJO Klasse halten nur Eigenschaften und Getter und Setter (DTO-style) ....

1) javadoc für die Eigenschaft zu schreiben javadoc
oder ...
2) schreiben javadoc für die Getter

Wenn ich javadoc für die Eigenschaft schreiben, meine IDE (Eclipse) wird (natürlich) nicht in der Lage sein, dies zu zeigen, wenn ich die POJO über Code zugreifen später Fertigstellung. Und es gibt kein Standard-Javadoc-Tag, mit dem ich das Getter-Javadoc mit der tatsächlichen 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; 
    } 

Also, im Grunde wäre es interessant zu erfahren, wie andere gehen über Ihre IDE Eclipse-Anzeige der javadoc Objektbeschreibung für Ihre Getter für mit - ohne den javadoc Kommentar zu duplizieren.

Ab jetzt überlege ich, meine Praxis nur die Getter zu dokumentieren und nicht die Eigenschaften. Aber es scheint nicht die beste Lösung zu sein ...

Answer 1

Sie können private Mitglieder beim Generieren von Javadocs (mit -Private) und dann verwenden Sie @ Link, um auf diese Felder-Eigenschaft zu verknüpfen.

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

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

Alternativ, wenn Sie die Javadoc für alle privaten Mitglieder nicht generieren möchten, können Sie eine Konvention haben alle Getter zu dokumentieren und @link auf Setter 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; 
    } 
} 

Answer 2

Ich mache beides, unterstützt von Eclipse Autocomplete.

Zuerst dokumentiere ich die Eigenschaft:

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

Dann habe ich kopieren und einfügen, dies dem Getter:

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

mit Eclipse, haben @return Aussagen eine Autovervollständigung - so, ich hinzufügen das Wort Gets, Kleinbuchstaben das "t", und kopieren Sie den Satz mit dem Kleinbuchstaben "t". Ich benutze dann @ return (mit Eclipse Autocomplete), fügen Sie den Satz ein, und dann das T groß in der Rückkehr. Es sieht dann wie folgt aus:

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

Schließlich habe ich Kopie, die Dokumentation an den Setzer:

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

Dann habe ich es ändern und mit Eclipse automatisch vervollständigen können Sie nicht nur die @ param-Tag bekommen, sondern auch der Name des Parameters:

/** 
* 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 daran zu erinnern, was die Eigenschaft durch Wiederholung 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. NULL-Eigenschaften nicht zulassen, Strings in Großbuchstaben umwandeln). Ich habe für diesen Zweck ein Eclipse-Plugin erstellt, aber ich konnte den passenden Erweiterungspunkt für den JDT nicht finden, also gab ich auf.

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

Answer 3

Ich denke wirklich, es ist ein Problem und die offizielle Javadoc guide sagt nichts darüber. C# kann dies auf elegante Weise mit der Verwendung von Properties lösen (ich code nicht in C#, aber ich denke wirklich, dass es ein nettes Feature ist).

Aber ich schätze: Wenn Sie erklären müssen, was ein String ist, ist es vielleicht ein "schlechtes kleines" über Ihren Code. Es kann bedeuten, dass Sie SomeClass schreiben sollten, um someString zu schreiben, also würden Sie erklären, was in der SomeClass-Dokumentation someString ist, und nur so, dass die Javadocs in Getter/Setter nicht notwendig wären.

Answer 4

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 Sie brauchen! Die Annotation @Getter erstellt eine Getter-Methode für jedes private Feld und hängt das Javadoc an sie an.

PS: Die Bibliothek hat viele coole Features Sie vielleicht