web-dev-qa-db-fra.com

Comment référencer une méthode dans javadoc?

Comment utiliser la balise @link pour créer un lien vers une méthode?

Je veux changer

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

à

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

mais je ne sais pas comment formater correctement la balise @link.

javahyperlinkjavadoc
764
Jason S

Vous trouverez de nombreuses informations sur JavaDoc à l'adresse spécification de commentaire sur la documentation pour le doclet Standard, y compris les informations sur la

{@ link package.class # membre label}

tag (que vous recherchez). L'exemple correspondant de la documentation est le suivant

Par exemple, voici un commentaire faisant référence à la méthode getComponentAt (int, int):

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

La partie package.class peut être omise si la méthode en question est dans la classe en cours.

Autres liens utiles sur JavaDoc sont:

1014
FrVaBe

Le format général, à partir de la section section @ link de la documentation javadoc , est le suivant:

{@link package.class#member label}

Exemples

Méthode dans la même classe: 

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

Méthode dans une classe différente, soit dans le même package, soit importé:

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

Méthode dans un package différent et non importé:

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

Libellé lié à la méthode, en texte brut plutôt que la police du code:

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

Une chaîne d'appels de méthode, comme dans votre question. Nous devons spécifier des étiquettes pour les liens vers des méthodes en dehors de cette classe, ou nous obtenons getFoo().Foo.getBar().Bar.getBaz(). Mais ces étiquettes peuvent être fragiles; voir "Étiquettes" ci-dessous.

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

Étiquettes

Le refactoring automatisé ne peut pas affecter les libellés. Ceci inclut le changement de nom de la méthode, de la classe ou du package; et changer la signature de la méthode.

Par conséquent, fournissez une étiquette uniquement si vous souhaitez un texte différent de celui par défaut.

Par exemple, vous pouvez créer un lien entre le langage humain et le code:

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

Vous pouvez également créer un lien à partir d'un exemple de code avec un texte différent de celui par défaut, comme indiqué ci-dessus sous "Chaîne d'appels de méthode". Toutefois, cela peut être fragile lorsque les API évoluent.

Tapez effacement et #member

Si la signature de la méthode inclut des types paramétrés, utilisez l’effacement de ces types dans javadoc @link. Par exemple:

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

/** See also {@link #bar(Collection)}. */
void foo() { ... }
679
Andy Thomas

vous pouvez utiliser @see pour le faire:

échantillon:

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();
    }
14
vuhung3990