Как ссылаться на метод в Javadoc? - PullRequest
Новая
       24

Как ссылаться на метод в Javadoc?

750 голосов
/ 06 мая 2011

Как я могу использовать тег @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.

Ответы [ 3 ]

989 голосов
/ 06 мая 2011

Вы найдете много информации о JavaDoc в Спецификации комментариев к документации для стандартного доклета , включая информацию о

{@ link package.class # метка участника}

тег (который вы ищете). Соответствующий пример из документации выглядит следующим образом

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

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

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

Другие полезные ссылки о JavaDoc:

668 голосов
/ 06 мая 2011

Общий формат из раздела @ ссылки документации javadoc :

{@link package.class#member label}

Примеры

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

/** 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() { ... }
14 голосов
/ 12 января 2017

вы можете использовать @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();
    }
...