example docs code all java javadoc

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.