Wie verweise ich auf eine Methode in Javadoc?

864

Wie kann ich das @linkTag verwenden, um eine Verknüpfung zu einer Methode herzustellen?

Ich will es verändern:

/**
 * 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()

zu:

/**
 * 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()

Ich weiß jedoch nicht, wie ich das @linkTag richtig formatieren soll .

Jason S.
quelle
22
Ich weiß, dass dies vor ein paar Jahren war, aber ... wenn Sie sich die offiziellen Java-Klassen ansehen, können Sie jede Form der Javadoc-Formatierung finden, die Sie benötigen. Schauen Sie sich zum Beispiel die HashMap Javadoc an.
Christophe Roussy

Antworten:

1122

Viele Informationen zu JavaDoc finden Sie in der Dokumentationskommentarspezifikation für das Standarddokument , einschließlich der Informationen auf der

{@link package.class # member label}

Tag (das Sie suchen). Das entsprechende Beispiel aus der Dokumentation lautet wie folgt

Hier ist beispielsweise ein Kommentar, der auf die Methode getComponentAt (int, int) verweist:

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

Das package.classTeil kann weggelassen werden, wenn sich die angegebene Methode in der aktuellen Klasse befindet.


Weitere nützliche Links zu JavaDoc sind:

FrVaBe
quelle
743

Das allgemeine Format aus dem Abschnitt @link der Javadoc-Dokumentation lautet:

{@link package.class # member label}

Beispiele

Methode in derselben Klasse:

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

Methode in einer anderen Klasse, entweder im selben Paket oder importiert:

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

Methode in einem anderen Paket und nicht importiert:

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

Mit der Methode verknüpfte Bezeichnung im Klartext anstelle der Codeschrift:

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

Eine Kette von Methodenaufrufen, wie in Ihrer Frage. Wir müssen Beschriftungen für die Links zu Methoden außerhalb dieser Klasse angeben, sonst erhalten wir getFoo().Foo.getBar().Bar.getBaz(). Diese Etiketten können jedoch zerbrechlich sein. siehe "Etiketten" unten.

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

Etiketten

Das automatisierte Refactoring wirkt sich möglicherweise nicht auf Etiketten aus. Dies umfasst das Umbenennen der Methode, Klasse oder des Pakets. und Ändern der Methodensignatur.

Geben Sie daher nur dann eine Beschriftung an , wenn Sie einen anderen als den Standardtext wünschen.

Sie können beispielsweise eine Verknüpfung von der menschlichen Sprache zum Code herstellen:

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

Oder Sie verknüpfen ein Codebeispiel mit einem anderen als dem Standardtext, wie oben unter "Eine Kette von Methodenaufrufen" gezeigt. Dies kann jedoch während der Entwicklung von APIs fragil sein.

Geben Sie erasure und #member ein

Wenn die Methodensignatur parametrisierte Typen enthält, verwenden Sie das Löschen dieser Typen im javadoc @link. Zum Beispiel:

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

/** See also {@link #bar(Collection)}. */
void foo() { ... }
Andy Thomas
quelle
Warten Sie: Ich möchte nur den Methodennamen mit einem Link, ich möchte auch nicht den Klassennamen.
Jason S
Ah, okay. Das erste Beispiel im obigen Link veranschaulicht dies.
Andy Thomas
1
+1 für die Bereitstellung eines Java 6-Links, mit dem ich auf der Oracle JavaDoc HowTo-Seite nicht verknüpft war. Ich komme immer noch nicht mit den Orakel-Links klar ... (feste Links zu Java 6 in meiner Antwort).
FrVaBe
@K. Claszen: download.oracle.com/javase/6/docs , klicken Sie im Diagramm auf javadoc , wählen Sie dann Javadoc Tool Reference Page (Microsoft Windows) und dann Javadoc-Tags .
Paŭlo Ebermann
@ Paŭlo Ebermann Danke! Ich werde versuchen, die Seite "docs" in Zukunft als Einstiegspunkt zu verwenden.
FrVaBe
16

Sie können dies verwenden @see:

Stichprobe:

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
quelle
4
OP: "Wie kann ich das @ link-Tag verwenden, um eine Verknüpfung zu einer Methode herzustellen?" Das @ link- Tag kann auf Anforderung des OP inline innerhalb eines Absatzes verwendet werden. Das @ see- Tag kann nicht. Weitere Einzelheiten finden Sie in dieser Frage .
Andy Thomas