Łącze Javadoc do metody w innej klasie

238

Obecnie odwołuję się do metod w innych klasach za pomocą następującej składni Javadoc:

@see {@link com.my.package.Class#method()}

I z tego, co rozumiem z dokumentacji, jest to właściwy sposób na zrobienie tego. Ale teraz do zabawnej części lub frustrujące. Kiedy generuję javadoc, przede wszystkim pojawia się następujący błąd:

warning - Tag @see:illegal character: "123" in "{@link com.my.package.Class#method()}"
warning - Tag @see:illegal character: "64" in "{@link com.my.package.Class#method()}"
warning - Tag @see: reference not found: {@link com.my.package.Class#method()}

Wygenerowany kod HTML tego:

"," <code>com.my.package.Class#method()}</code> ","

I oczywiście nie mam linku. Czy ktoś może mi powiedzieć, co się dzieje i jakieś wskazówki, jak to naprawić?

Według tabeli ASCII znaki 123 i 64 dla wold reprezentują {i @, więc dlaczego te znaki nie są poprawne, skoro ta składnia jest zgodna z dokumentacją?

java javadoc

— Robert
źródło

Wystarczy sprawdzić ... czy przeczytałeś dokumentację Javadoc Generator? docs.oracle.com/javase/7/docs/technotes/tools/windows/…

— Diogo Moreira

Czy zaimportowałeś com.my.package.Classw klasie, którą napisał JavaDoc? Odniesienia Nie znaleziono wydaje się dziwne. Z drugiej strony, nigdy nie użyłem ich w połączeniu, ale istnieje szansa, że @seei @linkkonflikt ze sobą, biorąc to @seegeneruje własną sekcję, nie zaskoczyłoby mnie to.

— Fritz

@DiogoMoreira - Nie, nie czytałem o silniku, ale sprawdzę to.

— Robert

@Gamb - Oczywiście, że nie jest to mój rzeczywisty wkład Javadoc ;-) Tak, wszystkie importy zostały wprowadzone.

— Robert

Podobny błąd występuje, jeśli umieścisz surowe hiperłącze jako wartość @seetagu w javadoc. Aby to naprawić w tym przypadku, umieść hiperłącze w elemencie zakotwiczenia HTML:/** @see <a href="http://example.com">Example</a> */

— cyber-mnich

Odpowiedzi:

280

W przypadku tagu Javadoc @seenie trzeba go używać @link; Javadoc utworzy dla ciebie link. Próbować

@see com.my.package.Class#method()

Oto więcej informacji na temat @see.

— rgettman
źródło

Dzięki za to właśnie przetestowałem to rozwiązanie i działa dobrze! Ale czytałem w tak wielu miejscach, że należy skorzystać z linku w See uzyskać to do pracy, więc to trochę dziwne ...

— Robert

Można używać @linkw innych miejscach, które nie Javadoc już przekształcić w link, na przykład w opisie @param, w opisie @return, w głównej części opisu, itp

— rgettman

kiedy tylko tego spróbowałem, wyświetla metodę jako zwykły tekst, nie można jej kliknąć tak jak my @see dla metody lokalnej.

— JesseBoyd

146

Poza @seetym bardziej ogólnym sposobem odwoływania się do innej klasy i ewentualnie metody tej klasy jest {@link somepackage.SomeClass#someMethod(paramTypes)}. Ma to tę zaletę, że można je wykorzystać w środku opisu javadoc.

Z dokumentacji javadoc (opis znacznika @link) :

Ten znacznik jest bardzo podobny do @see - oba wymagają tych samych referencji i akceptują dokładnie tę samą składnię dla elementu package.class # i etykiety. Główną różnicą jest to, że {@link} generuje link w linii, zamiast umieszczać link w sekcji „Zobacz także”. Tag {@link} zaczyna się i kończy nawiasami klamrowymi, które oddzielają go od reszty tekstu w wierszu.

— Javarome
źródło

Tak więc rozwiązaniem pierwotnego problemu jest to, że nie potrzebujesz zarówno odniesienia „@see”, jak i „{@link ...}” w tym samym wierszu. Tag „@link” jest samowystarczalny i, jak wspomniano, można go umieścić w dowolnym miejscu bloku javadoc. Możesz więc łączyć dwa podejścia:

/**
 * some javadoc stuff
 * {@link com.my.package.Class#method()}
 * more stuff
 * @see com.my.package.AnotherClass
 */

— Dave Hentchel
źródło

Należy zaakceptować odpowiedź, ponieważ dwie pozostałe odpowiedzi nie pokazują, że „@link” lub „@see” muszą znajdować się w komentarzu w wielu wierszach / ** * / nie w jednym wierszu

— Stoycho Andreev

@Sniper, {@link }działa dobrze w jednowierszowym komentarzu Javadoc, czy może masz na myśli fakt, że nie działają one z komentarzami zaczynającymi się od //? /** */jest Javadoc i jest niezbędny dla wszystkich funkcji Javadoc.

— Jase

Tak @Jase Spotkałem dokładnie to komentarz musi być / ** * /, ale nie //

— Stoycho Andreev

@Sniper Nie sądzę, że wymaga to odpowiedzi, ponieważ jest to pytanie Javadoc na początek - należy ogólnie zrozumieć, że Javadoc działa tylko w komentarzach Javadoc.

— Jase

@Jase w pewnym stopniu się z tobą zgadza, ale uważam, że źródło informacji, takie jak Stackoverflow, wymaga wyjaśnień przykładami, a nie cytatami z dokumentacji Oracle lub innej dokumentacji, co oczywiście nie jest jasne. Ta odpowiedź jest jedyną odpowiedzią, która ma przykład, powyżej dwóch odpowiedzi są cytatami.

— Stoycho Andreev