Javadoc @see o {@link}?

Question

¿Podría alguien decirme la diferencia entre javadoc @see y {@link}?

O más bien, ¿cuándo usar cuál de ellos?

Answer 1

El official guidelines en esto es bastante claro.

Las diferencias funcionales son:

• {@link} es un enlace en línea y se puede colocar donde quiera
• @see crea su propia sección

En mi opinión, {@link} se utiliza mejor cuando Literalmente usa un nombre de clase, campo, constructor o método en su descripción. El usuario podrá hacer clic en el javadoc de lo que ha vinculado.

utilizo 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 de una gran variedad de cosas en la biblioteca estándar.

Answer 2

@see crea una línea aislada en los Javadocs. {@link} es para incrustar dentro de texto.

Uso @see cuando es una entidad relacionada, pero no me refiero a ella en el texto expositivo. Utilizo enlaces dentro del texto cuando hay un acoplamiento cerrado, o (creo) es probable que el lector se beneficie de la sugerencia de navegación, por ejemplo, tendrá que consultarlo directamente.