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!
@seewMethodB„s javadoc i odniesieniaMethodAponieważ 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 ...Odpowiedzi:
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 :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.
źródło
@seejest również przydatny do tworzenia linków do alternatyw@Deprecatedmetod.@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@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.
źródło
Dobrym przykładem sytuacji, w której
@seemoże być przydatna, byłoby zaimplementowanie lub przesłonięcie metody interfejsu / klasy abstrakcyjnej. Deklaracja miałabyjavadocsekcję 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źródło
@inheritDockopiuje dokumentację z innej lokalizacji. Wyobrażam sobie, że opisywanie szczegółów zamiast dodawania puchu ma swoje zastosowanie?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ą@inheritDoci 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.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
źródło