docs - Javadoc @see o{@link}?
javadoc wiki (2)
Las pautas oficiales sobre esto son bastante claras.
Las diferencias funcionales son:
-
{@link}
es un enlace en línea y se puede colocar donde quieras -
@see
crea su propia sección
En mi opinión, {@link}
se usa mejor cuando, literalmente, utilizas un nombre de clase, campo, constructor o método en tu descripción. El usuario podrá hacer clic en el javadoc de lo que ha vinculado.
Uso la anotación @see
en 2 casos:
- Algo es muy relevante pero no se menciona en la descripción.
- Me refiero a lo mismo varias veces en la descripción, y se utiliza como reemplazo de múltiples enlaces a la misma.
Basé esta opinión en la comprobación aleatoria de la documentación para una gran variedad de cosas en la biblioteca estándar.
¿Podría alguien decirme la diferencia entre javadoc @see
y {@link}
?
O más bien, ¿cuándo usar cuál de ellos?
@see
crea una línea aislada en los Javadocs. {@link}
es para incrustación dentro del texto.
Utilizo @see
cuando se trata de una entidad relacionada, pero no me refiero a ella en el texto expositivo. Utilizo enlaces dentro del texto cuando hay acoplamiento ajustado, o (creo) es probable que el lector se beneficie de la sugerencia de navegación, por ejemplo, tendrá que hacer referencia directamente.