Wykorzystanie @see w JavaDoc?

110

Kiedy mam do @seeczynienia z JavaDocs? Jakie jest jego zastosowanie?

Na przykład, jeśli MethodArozmowy MethodBpotem muszę umieścić @seew MethodB„s javadoc i odniesienia MethodAponieważ to, co się nazywa, czy muszę umieścić odniesienie do MethodBz MethodA, ponieważ jest to powołanie. Przeczytałem informacje @seena stronie Oracle i wydaje mi się, że są one niewiarygodnie niejasne, mówi, że oznacza „zobacz też”, ale nie do końca, co to znaczy!

java methods javadoc

— Jeff
źródło

4

umieścić @seew MethodB„s javadoc i odniesienia MethodAponieważ to, co się nazywa -> Jak byłoby to możliwe, aby poznać wszystkie metody, które wymagają jednego ze swoich metod? Nawet jeśli jest to możliwe (powiedzmy, że prywatna metoda została użyta tylko raz) łączenie od dzwoniącego do dzwoniącego brzmi co najmniej dziwnie ...

— Mr_and_Mrs_D

1

Oznacza to, co zazwyczaj oznacza w języku angielskim: oxforddictionaries.com/us/definition/american_english/see (definicja 1.4)

— stackexchanger

119

Tak, to jest dość niejasne.

Powinieneś go używać, gdy dla czytelników dokumentacji twojej metody może być przydatne przyjrzenie się także innej metodzie. Jeśli w dokumentacji metody A jest napisane „Działa jak metoda B, ale…”, z pewnością powinieneś umieścić link. Alternatywą dla @seebyłby {@link ...}tag wbudowany :

/**
 * ...
 * Works like {@link #methodB}, but ...
 */

Kiedy fakt, że methodA wywołuje metodę MethodB, jest szczegółem implementacji i nie ma rzeczywistego związku z zewnątrz, nie potrzebujesz tutaj linku.

— Paŭlo Ebermann
źródło

13

@seejest również przydatny do tworzenia linków do alternatyw @Deprecatedmetod.

— Mauve Ranger

1

@MauveRanger Ponieważ @seejest dość niejasny, w przypadku przestarzałych rzeczy uważam, że bardziej przydatne jest zrobienie czegoś bardziej wyraźnego, na przykład:@deprecated since X.Y.Z; use {@link #alternateMethod()} instead

— Christopher,

10

@see jest przydatne w przypadku informacji o powiązanych metodach / klasach w interfejsie API. Stworzy link do metody / kodu, do którego się odwołujesz w dokumentacji. Użyj go, gdy istnieje powiązany kod, który może pomóc użytkownikowi zrozumieć, jak używać interfejsu API.

— Rob Dawson
źródło

9

Dobrym przykładem sytuacji, w której @seemoże być przydatna, byłoby zaimplementowanie lub przesłonięcie metody interfejsu / klasy abstrakcyjnej. Deklaracja miałaby javadocsekcję opisującą szczegółowo metodę, a zastąpiona / zaimplementowana metoda mogłaby używać @seetagu, odwołując się do podstawowej.

Powiązane pytanie: Pisanie poprawnego javadoc z @see?

Dokumentacja Java SE: @see

— AtomHeartFather
źródło

2

nie ja, ale prawdopodobnie dlatego, że mamy @inheritDoc docs.oracle.com/javase/6/docs/technotes/tools/solaris/ ...

1

dokumentacja java dla @see jest naprawdę dobra. powinien być pierwszy.

— dok,

2

@vaxquis @inheritDockopiuje dokumentację z innej lokalizacji. Wyobrażam sobie, że opisywanie szczegółów zamiast dodawania puchu ma swoje zastosowanie?

— Nielsvh

@Nielsvg ta odpowiedź wspomina o tym the overridden/implemented method could use a @see tag, referring to the base one.- i to jest dokładnie to, do czego @inheritDocsłuży; IMO lepiej jest zamieścić opis klasy bazowej dosłownie za pomocą @inheritDoc i w razie potrzeby uzupełnić, niż odnosić się do niego @see- patrz (sic!) Stackoverflow.com/questions/11121600/… ; wielu programistów (w tym ja) woli mieć wszystkie szczegóły implementacji w jednym miejscu, zamiast niekończącego się łańcucha linków w górę prowadzących w górę przez hierarchię dziedziczenia.

2

Używam @see do opisywania metod klasy implementacji interfejsu, gdzie opis metody jest już dostarczony w javadoc interfejsu. Kiedy to robimy, zauważam, że Eclipse pobiera dokumentację interfejsu, nawet gdy szukam metody na referencji implementacji podczas tworzenia kodu

— Maruthi
źródło