Jak odwołać się do metody w javadoc?

864

Jak mogę użyć @linktagu, aby połączyć się z metodą?

Chcę się zmienić:

/**
 * Returns the Baz object owned by the Bar object owned by Foo owned by this.
 * A convenience method, equivalent to getFoo().getBar().getBaz()
 * @return baz
 */
public Baz fooBarBaz()

do:

/**
 * Returns the Baz object owned by the Bar object owned by Foo owned by this.
 * A convenience method, equivalent to {@link getFoo()}.{@link getBar()}.{@link getBaz()}
 * @return baz
 */
public Baz fooBarBaz()

ale nie wiem jak @linkpoprawnie sformatować tag.

Jason S.
źródło
22
Wiem, że to jest kilka lat temu, ale ... przeglądanie oficjalnych klas Java może pomóc w znalezieniu dowolnej formy formatowania Javadoc, której potrzebujesz. Na przykład spójrz na HashMap Javadoc.
Christophe Roussy

Odpowiedzi:

1121

Wiele informacji na temat JavaDoc można znaleźć w specyfikacji komentarza do dokumentacji standardowego dokumentu , w tym na stronie

{@link package.class # etykieta członka}

tag (którego szukasz). Odpowiedni przykład z dokumentacji jest następujący

Na przykład tutaj jest komentarz odnoszący się do metody getComponentAt (int, int):

Use the {@link #getComponentAt(int, int) getComponentAt} method.

package.classCzęść może być mowa, pominięte jeśli metoda jest w obecnej klasie.


Inne przydatne linki na temat JavaDoc to:

FrVaBe
źródło
743

Ogólny format z sekcji @link dokumentacji javadoc to:

{@link package.class # etykieta członka}

Przykłady

Metoda w tej samej klasie:

/** See also {@link #myMethod(String)}. */
void foo() { ... }

Metoda w innej klasie, w tym samym pakiecie lub zaimportowana:

/** See also {@link MyOtherClass#myMethod(String)}. */
void foo() { ... }

Metoda w innym pakiecie i nie zaimportowana:

/** See also {@link com.mypackage.YetAnotherClass#myMethod(String)}. */
void foo() { ... }

Etykieta połączona z metodą, zwykłym tekstem, a nie czcionką:

/** See also this {@linkplain #myMethod(String) implementation}. */
void foo() { ... }

Łańcuch wywołań metod, jak w twoim pytaniu. Musimy określić etykiety dla linków do metod poza tą klasą, albo otrzymamy getFoo().Foo.getBar().Bar.getBaz(). Ale te etykiety mogą być kruche; patrz „Etykiety” poniżej.

/**
 * A convenience method, equivalent to 
 * {@link #getFoo()}.{@link Foo#getBar() getBar()}.{@link Bar#getBaz() getBaz()}.
 * @return baz
 */
public Baz fooBarBaz()

Etykiety

Automatyczne refaktoryzacja nie może wpływać na etykiety. Obejmuje to zmianę nazwy metody, klasy lub pakietu; i zmiana podpisu metody.

Dlatego podaj etykietę tylko wtedy, gdy chcesz mieć inny tekst niż domyślny.

Na przykład możesz utworzyć link z ludzkiego języka do kodu:

/** You can also {@linkplain #getFoo() get the current foo}. */
void setFoo( Foo foo ) { ... }

Lub możesz linkować z przykładowego kodu z tekstem innym niż domyślny, jak pokazano powyżej w „Łańcuch wywołań metod”. Może to jednak być kruche, gdy interfejsy API ewoluują.

Wpisz kasowanie i #member

Jeśli podpis metody zawiera sparametryzowane typy, użyj kasowania tych typów w javadoc @link. Na przykład:

int bar( Collection<Integer> receiver ) { ... }

/** See also {@link #bar(Collection)}. */
void foo() { ... }
Andy Thomas
źródło
Czekaj: chcę tylko nazwę metody z linkiem, nie chcę też nazwy klasy.
Jason S
Ah, dobrze. Ilustruje to pierwszy przykład w powyższym linku.
Andy Thomas
1
+1 za udostępnienie linku Java 6, z którym nie byłem powiązany ze strony HowTo Oracle JavaDoc. Nadal nie mogę się dogadać z linkami wyroczni ... (naprawiłem linki do Java 6 w mojej odpowiedzi).
FrVaBe
@K. Claszen: download.oracle.com/javase/6/docs , następnie kliknij javadoc na diagramie, a następnie wybierz Strona informacyjna narzędzia Javadoc (Microsoft Windows) , a następnie tagi Javadoc .
Paŭlo Ebermann
@ Paŭlo Ebermann Thanks! W przyszłości spróbuję użyć strony „Dokumenty” jako punktu wejścia.
FrVaBe,
16

możesz użyć @seedo tego:

próba:

interface View {
        /**
         * @return true: have read contact and call log permissions, else otherwise
         * @see #requestReadContactAndCallLogPermissions()
         */
        boolean haveReadContactAndCallLogPermissions();

        /**
         * if not have permissions, request to user for allow
         * @see #haveReadContactAndCallLogPermissions()
         */
        void requestReadContactAndCallLogPermissions();
    }
vuhung3990
źródło
4
OP: „Jak mogę użyć tagu @link, aby połączyć się z metodą?” @Link tag może być używany w inline ustępu, zgodnie z wnioskiem PO. @See tag nie może. Zobacz więcej szczegółów na to pytanie .
Andy Thomas