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 ...
Odpowiedzi:
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; } }
źródło
@link
oznacza 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.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!
@Getter
Adnotacja 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ć
źródło
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.
źródło
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.
źródło