Jak napisać Javadoc właściwości?

Często napotykam dylemat, pisząc javadoc dla właściwości / elementów „prostej” klasy POJO zawierającej tylko właściwości oraz metody pobierające i ustawiające (w stylu DTO) ....

1) Napisz javadoc dla właściwości
lub ...
2) Napisz javadoc dla metody pobierającej

Jeśli napiszę javadoc dla tej właściwości, moje IDE (Eclipse) (naturalnie) nie będzie w stanie tego wyświetlić, gdy później uzyskam dostęp do POJO poprzez uzupełnianie kodu. I nie ma standardowego tagu javadoc, który pozwala mi połączyć getter-javadoc z rzeczywistą właściwością javadoc.

Przykład:

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

Tak więc, w zasadzie byłoby interesujące posłuchać, jak inni robią, aby Twoje Eclipse IDE wyświetlało opis właściwości javadoc dla twoich pobierających - bez konieczności powielania komentarza javadoc.

Obecnie rozważam praktykę dokumentowania tylko metod pobierających, a nie właściwości. Ale to nie wydaje się być najlepszym rozwiązaniem ...

Możesz dołączyć prywatnych członków podczas generowania Javadoc (używając -private), a następnie użyć @link, aby połączyć się z tą właściwością pól.

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

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

Alternatywnie, jeśli nie chcesz generować Javadoc dla wszystkich prywatnych członków, możesz mieć konwencję dokumentowania wszystkich pobierających i używania @link na ustawiaczach.

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 to bardzo wygodna biblioteka do takich zadań.

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

To wszystko, czego potrzebujesz! @GetterAdnotacja tworzy metodę getter dla każdego pola prywatnego i dołączyć do niego javadoc.

PS : Biblioteka ma wiele fajnych funkcji, które możesz chcieć sprawdzić

Robię jedno i drugie, wspomagane przez autouzupełnianie Eclipse.

Najpierw dokumentuję nieruchomość:

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

Następnie kopiuję i wklejam to do gettera:

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

W przypadku zaćmienia instrukcje @return mają autouzupełnianie - więc dodaję słowo Gets, małe litery „t” i kopiuję zdanie małymi literami „t”. Następnie używam @return (z autouzupełnianiem Eclipse), wklejam zdanie, a następnie wielkie litery T w powrocie. Wygląda to następująco:

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

Na koniec kopiuję tę dokumentację do ustawiającego:

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

Następnie modyfikuję go i dzięki autouzupełnianiu Eclipse można uzyskać nie tylko tag @param, ale także nazwę parametru:

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

Wtedy jestem skończony. Moim zdaniem to szablonowanie znacznie ułatwia, na dłuższą metę, nie tylko przypominanie sobie, co oznacza właściwość poprzez powtórzenie, ale także ułatwia dodawanie dodatkowych komentarzy do gettera i settera, jeśli chcesz dodać stronę efekty (takie jak niedozwolenie właściwości zerowych, zamiana łańcuchów na wielkie litery itp.). Badałem tworzenie wtyczki Eclipse w tym celu, ale nie mogłem znaleźć odpowiedniego punktu rozszerzenia dla JDT, więc poddałem się.

Zwróć uwagę, że zdanie nie zawsze może zaczynać się od litery T - po prostu pierwsza litera musi być niekapitalizowana / rekapitalizowana podczas wklejania.

Naprawdę uważam, że to problem, a oficjalny przewodnik Javadoc nic o tym nie mówi. C # może rozwiązać ten problem w elegancki sposób przy użyciu właściwości (nie koduję w C #, ale naprawdę uważam, że to fajna funkcja).

Ale zgaduję: jeśli chcesz wyjaśnić, czym jest someString, być może jest to `` zły mały '' w twoim kodzie. Może to oznaczać, że powinieneś napisać SomeClass, aby wpisać someString, więc wyjaśniłbyś, czym jest someString w dokumentacji SomeClass, i żeby javadoc w getter / setter nie był potrzebny.