¿Cómo hacer referencia a un método en javadoc?
¿ Cómo puedo usar la @linketiqueta para vincular a un método?
Quiero cambiar:
/**
* 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()
a:
/**
* 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()
pero no sé cómo formatear la @linketiqueta correctamente.
Encontrará mucha información sobre JavaDoc en la Especificación de comentarios de documentación para el Doclet estándar , incluida la información sobre el
{@módulo de enlace/paquete.clase#etiqueta de miembro}
etiqueta (que estás buscando). El ejemplo correspondiente de la documentación es el siguiente.
Por ejemplo, aquí hay un comentario que hace referencia al método getComponentAt(int, int):
Use the {@link #getComponentAt(int, int) getComponentAt} method.
La module/package.classparte se puede omitir si el método referido está en la clase actual.
Otros enlaces útiles sobre JavaDoc son:
- Especificaciones de la herramienta JDK 17: el comando javadoc
- Guía de JavaDoc
- Cómo escribir comentarios de documentos para la herramienta Javadoc
El formato general, de la sección @link de la documentación javadoc , es:
Ejemplos
Método en la misma clase:
/** See also {@link #myMethod(String)}. */
void foo() { ... }
Método en una clase diferente, ya sea en el mismo paquete o importado:
/** See also {@link MyOtherClass#myMethod(String)}. */
void foo() { ... }
Método en un paquete diferente y no importado:
/** See also {@link com.mypackage.YetAnotherClass#myMethod(String)}. */
void foo() { ... }
Etiqueta vinculada al método, en texto sin formato en lugar de fuente de código:
/** See also this {@linkplain #myMethod(String) implementation}. */
void foo() { ... }
Una cadena de llamadas a métodos, como en tu pregunta. Tenemos que especificar etiquetas para los enlaces a métodos fuera de esta clase, o obtendremos getFoo().Foo.getBar().Bar.getBaz(). Pero estas etiquetas pueden ser frágiles durante la refactorización; consulte "Etiquetas" a continuación.
/**
* A convenience method, equivalent to
* {@link #getFoo()}.{@link Foo#getBar() getBar()}.{@link Bar#getBaz() getBaz()}.
* @return baz
*/
public Baz fooBarBaz()
Etiquetas
Es posible que la refactorización automatizada no afecte las etiquetas. Esto incluye cambiar el nombre del método, clase o paquete; y cambiar la firma del método.
Por lo tanto, proporcione una etiqueta sólo si desea un texto diferente al predeterminado.
Por ejemplo, puedes vincular el lenguaje humano al código:
/** You can also {@linkplain #getFoo() get the current foo}. */
void setFoo( Foo foo ) { ... }
O puede vincular desde un ejemplo de código con texto diferente al predeterminado, como se muestra arriba en "Una cadena de llamadas a métodos". Sin embargo, esto puede resultar frágil mientras las API evolucionan.
Escribe borrado y #miembro
Si la firma del método incluye tipos parametrizados, utilice el borrado de esos tipos en el javadoc @link. Por ejemplo:
int bar( Collection<Integer> receiver ) { ... }
/** See also {@link #bar(Collection)}. */
void foo() { ... }
