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

93

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 ...


źródło
1
Ciekawa dyskusja na ten temat tutaj: stackoverflow.com/questions/1028967/… . Zaakceptowana odpowiedź dotyczy tego, o co pytałeś o Eclipse / javadoc.
Rok
Wygląda na to, że zakończyli to, co rozważałem ... Napisz własność javadoc tylko w getterach.
Znalazłem sposób, aby to zrobić za pomocą adnotacji, które działają w zaćmieniu i mogą być nawet gromadzone w czasie wykonywania, czy byłaby to opcja?
Aquarius Power
członkowie prywatni potrzebują javadoc?
teon
Nazwa bla bla bla: najlepszy przykład
Rodrigo Espinoza

Odpowiedzi:

76

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;
    }
}
Chandra Sekar
źródło
2
Eksperymentowałem zarówno z tagami @link, jak i @see .. Ale ... przynajmniej Eclipse nie wyświetla tego poprawnie. Eclipse wyświetla link jako… (drumroll)… link…, który trzeba kliknąć, aby zobaczyć zawartość. Chcę móc aktywować uzupełnianie kodu (lub po najechaniu myszą) uzyskać javadoc dla właściwości, gdy faktycznie przeglądam getter ...
13
@Kenny - nie modeluj swoich praktyk JavaDoc z punktu widzenia użyteczności Eclipse. Zrób to z punktu widzenia, aby uzyskać poprawne (lub wystarczająco dobre) wyjście JavaDoc. IDE zmienić, a co może być niewystarczające dzisiaj może być skierowana jutro (lub może faktycznie zmienić IDE całkowicie.)
luis.espinal
1
@luis @linkoznacza link, który należy kliknąć, aby zobaczyć rzeczywisty javadoc. To nie jest problem z użytecznością Eclipse, jest to niewłaściwe rozwiązanie dla dostarczania javadoców, które są łatwe w użyciu.
NateS,
4

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ć

Amanuel Nega
źródło
3

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.

MetroidFan2002
źródło
24
Kopiowanie / wklejanie jest złe ... i czasochłonne. Te kroki wyglądają na dużo pracy, a jeśli zmieni się javadoc, będziesz mieć 3 różne miejsca do aktualizacji. Nie sądzę, żeby wtyczka też to usprawiedliwiała ... przynajmniej wtedy wtyczka musiałaby np. Uznać właściwość javadoc za wzorzec, a następnie nadpisać metody pobierające (i ustawiające). To, co chcę osiągnąć, to napisać javadoc w jednym miejscu, a potem oba gettery i właściwość javadocs przyjmą ten sam opis ...
Zazwyczaj właściwości nie zmieniają się zbyt często. Operacje kopiowania i wklejania z autouzupełnianiem Eclipse trwają mniej niż 30 sekund po skonstruowaniu właściwości Javadoc.
MetroidFan2002
4
Nie jestem przekonany ... Wprowadzenie tego typu schematu kopiowania / wklejania jest zobowiązane przez IMHO prowadzić do niespójności. Za mało wierzę w to, że inni kucharze (lub ja) edytują później kod. Ponadto, przynajmniej jeśli nie masz kompletnego wstępnego projektu, właściwości javadoc często podlegają zmianom, przynajmniej na etapie eksperymentalnym / projektowym. A javadoc będzie lepszej jakości, jeśli zostanie napisany, gdy kod będzie świeży ... Przepraszam, jeśli wyglądam na jęczącego ;-)
1
Przykro nam, ale właściwości edycji z pewnością prowadzą do niespójności - tak czy inaczej, Javadoc ma tendencję do upuszczania się, chyba że jest energicznie utrzymywany w jakiś sposób. Nawet jeśli istniał łatwy sposób ujawnienia właściwości javadoc, jest równie prawdopodobne, że sama właściwość javadoc nie zostanie zaktualizowana. To naprawdę kwestia konwencji kodowania zespołu, itp., Recenzji kodu, takich rzeczy - powodzenia, tak to robię, więc nie zapomnę.
MetroidFan2002
@Metroid - chyba że jest w jakiś sposób energicznie utrzymywany - cóż, ma być energicznie utrzymywany, jeśli jest traktowany jako część samego kodu źródłowego. I nie traktowanie komentarzy Javadoc (i ich odpowiedników w innych językach) jako nieodłącznej części kodu, choć niestety jest to standardowa praktyka, jest źródłem wielu zła. Najgorszy komentarz to ten, który stał się przestarzały. W najlepszym przypadku spowalniają programistów przed opanowaniem kodu (ponieważ muszą stale weryfikować i akceptować / odrzucać nieaktualne komentarze). Co gorsza, podają podatne na błędy, wprowadzające błędy informacje.
luis.espinal
0

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.

Leonardo Leite
źródło
1
Jeśli chodzi o niewłaściwe użycie ciągów znaków w kodzie, zapoznaj się z tematem `` Unikaj ciągów znaków, w których inne typy są bardziej odpowiednie '' w książce Effective Java.
Leonardo Leite