Как я могу использовать тег @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
.
Вы найдете много информации о JavaDoc в спецификации комментариев к документации для стандартного доклета, включая информацию о
тег (который вы ищете). Соответствующий пример из документации выглядит следующим образом
Например, вот комментарий, который ссылается на метод getComponentAt (int, int):
Use the {@link #getComponentAt(int, int) getComponentAt} method.
Часть package.class
может быть опущена, если указанный метод находится в текущем классе.
Другие полезные ссылки о JavaDoc:
Общий формат из раздела @link документации javadoc:
Метод в том же классе:
/** 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 развиваются.
Если сигнатура метода включает параметризованные типы, используйте удаление этих типов в javadoc @link. Например:
int bar( Collection<Integer> receiver ) { ... }
/** See also {@link #bar(Collection)}. */
void foo() { ... }
вы можете использовать @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();
}