Як посилатися на метод у javadoc?


864

Як я можу використовувати @linkтег для посилання на метод?

Я хочу змінити:

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

але я не знаю, як правильно відформатувати @linkтег.


22
Я знаю, що це кілька років тому, але ... перегляд офіційних класів Java може допомогти знайти будь-яку форму форматування Javadoc, яка вам потрібна. Наприклад, подивіться на HashMap Javadoc.
Крістоф Руссі

Відповіді:


1122

Докладну інформацію про JavaDoc ви знайдете в Специфікації коментарів до документації для стандартного Doclet , включаючи інформацію про

{@link package.class # член мітки}

тег (який ви шукаєте). Відповідний приклад з документації є наступним

Наприклад, ось коментар, який стосується методу getComponentAt (int, int):

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

package.classЧастина може бути опущена , якщо згаданий метод в поточному класі.


Інші корисні посилання про JavaDoc:


743

Загальний формат із розділу @link документації на javadoc :

{@link package.class # член мітки}

Приклади

Метод у тому ж класі:

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

Метод в іншому класі, або в одній упаковці, або імпортованому:

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

Спосіб у іншій упаковці, а не імпортований:

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

Мітка, пов'язана з методом, у простому тексті, а не в шрифті коду:

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

Ланцюжок методів викликів, як у вашому питанні. Ми повинні вказати мітки для посилань на методи поза цим класом, або ми отримаємо getFoo().Foo.getBar().Bar.getBaz(). Але ці мітки можуть бути крихкими; див. "Етикетки" нижче.

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

Мітки

Автоматизоване рефакторинг може не впливати на етикетки. Це включає перейменування методу, класу чи пакета; та зміна підпису методу.

Тому вкажіть мітку лише в тому випадку, якщо ви хочете, щоб текст був іншим, ніж за замовчуванням.

Наприклад, ви можете зв’язати з людської мови на код:

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

Або ви можете зв’язати з зразка коду текст, відмінний від типового, як показано вище у розділі "Ланцюжок викликів методу". Однак це може бути неміцним, коли API розвиваються.

Наберіть стирання та #member

Якщо підпис методу включає параметризовані типи, використовуйте стирання цих типів у javadoc @link. Наприклад:

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

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

Зачекайте: я просто хочу назву методу із посиланням, я також не хочу назвати клас.
Jason S

Ага, гаразд. Перший приклад у посиланні вище ілюструє це.
Енді Томас

1
+1 за надання посилання Java 6, до якого я не пов’язаний зі сторінки Oracle JavaDoc HowTo. Я досі не можу погодитися з посиланнями на oracle ... (фіксовані посилання на Java 6 у моїй відповіді).
FrVaBe

@K. Claszen: download.oracle.com/javase/6/docs , потім натисніть на діаграмі javadoc , потім оберіть довідкову сторінку інструмента Javadoc (Microsoft Windows) , потім теги Javadoc .
Paŭlo Ebermann

@ Paŭlo Ebermann Дякую! Спробуємо використовувати сторінку "Документи" як точку входу в майбутньому.
FrVaBe

16

ви можете використовувати @seeдля цього:

зразок:

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

4
ОП: "Як я можу використовувати тег @link для посилання на метод?" @Link тег може бути використаний вбудований в пункті, в відповідно до проханням ОП. @See тег не може. Детальніше в цьому питанні див .
Енді Томас
Використовуючи наш веб-сайт, ви визнаєте, що прочитали та зрозуміли наші Політику щодо файлів cookie та Політику конфіденційності.
Licensed under cc by-sa 3.0 with attribution required.