Szczegóły różnicy między @see i @inheritDoc

87

Przejrzałem odniesienie do JavaDoc i chociaż rozumiem podstawową różnicę między @see(różnymi linkami) a {@inheritDoc}(eksport komentarza JavaDoc nadklasy), potrzebuję wyjaśnienia, jak rzeczy faktycznie zostały zaimplementowane.

W środowisku Eclipse IDE, kiedy wybiorę opcję „Generuj komentarze elementu” dla metody dziedziczonej (z interfejsu lub zastąpienia toString () itd.), Tworzy następujący komentarz

/* (non-Javadoc)
 * @see SomeClass#someMethod()
 */

Jeśli jestem zobowiązany do produkcji JavaDoc powinienem pozostawić go na tym, wymienić @seesię {@inheritDoc}lub przekształcić go w bona fide JavaDoc jako takie:

/**
 * {@inheritDoc}
 */

A kiedy to zrobię, czy nadal powinienem zachować flagę metody class #?

java javadoc comments theUg
źródło

Odpowiedzi:

143

Przede wszystkim należy usunąć oryginalny szablon zaćmienia, ponieważ to tylko hałaśliwe śmieci. Wstaw znaczące dokumenty lub nie umieszczaj niczego. Ale bezużyteczne przekształcanie oczywistego przy użyciu szablonów IDE po prostu zaśmieca kod.

Po drugie, jeśli są wymagane do produkcji javadoc, to mieć , aby rozpocząć komentarz z /**. W przeciwnym razie nie jest to javadoc.

Na koniec, jeśli zastępujesz, powinieneś użyć @inheritDoc(zakładając, że chcesz dodać do oryginalnych dokumentów, jak @seh zauważył w komentarzu, jeśli chcesz tylko zduplikować oryginalne dokumenty, nie potrzebujesz niczego). @seepowinny być używane tylko do odwoływania się do innych pokrewnych metod.

jtahlborn
źródło
75
Powinieneś używać tylko @inheritDocwtedy, gdy zamierzasz dodać do oryginalnej dokumentacji nadklasy. Jeśli chcesz tylko, aby została zduplikowana, Javadoc już to zrobi, zauważając, że dokumentacja nadklasy dotyczy metody nadpisanej podklasy, ponieważ podklasa nie dostarczyła dodatkowej dokumentacji.
seh
4
Wygenerowałem dokumenty zi bez @inheritDoci nie widzę żadnej różnicy. Nawet bez tego @inheritDocwidzę, że Javadoc klasy pochodnej został dołączony do klasy bazowej.
randominstanceOfLivingThing
Przyszedłem tutaj, ponieważ checkstyle narzeka, że ​​"metoda nie jest przeznaczona do przedłużania". Dobrym pomysłem może być użycie, @inheritDoca następnie dodanie dokumentacji specyficznej dla implementacji, np. W jaki sposób implementuje / nadpisuje metodę macierzystą, a zwłaszcza DLACZEGO robi to tak, jak robi.
Ben