Javadoc @see o {@link}?

184

¿Alguien podría decirme la diferencia entre javadoc @seey {@link}?

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

java javadoc

— miembros
fuente

213

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 usas 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.

Yo uso la @seeanotación 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 usa como reemplazo de múltiples enlaces a la misma.

Basé esta opinión en verificar aleatoriamente la documentación de una gran variedad de cosas en la biblioteca estándar.

— MarioDS
fuente

3

El javadoc advierte que @link es bastante intensivo y debe usarse solo cuando sea necesario.

— Thomas

44

Para cualquiera que esté buscando, puede obtener detalles sobre esto (incluida la advertencia sobre @linkel comentario anterior) en la guía Javadoc de Oracle .

— Ash Ryan Arnwine

48

@seecrea una línea aislada en los Javadocs. {@link}es para incrustar en el texto.

Lo uso @seecuando es una entidad relacionada pero no me refiero a él en el texto expositivo. Uso enlaces dentro del texto cuando hay un acoplamiento estrecho, o (creo) es probable que el lector se beneficie de la sugerencia de navegación, por ejemplo, tendrá que hacer referencia a él directamente.

— Dave Newton
fuente

3

Hay otra referencia (sección de desaprobación) mismos documentos oficiales que prefieren {@link}más @see(ya que Java 1.2):

Para Javadoc 1.2 y versiones posteriores, el formato estándar es usar la etiqueta @deprecated y la etiqueta en línea {@link}. Esto crea el enlace en línea, donde lo desee. Por ejemplo:

Para Javadoc 1.1, el formato estándar es crear un par de etiquetas @deprecated y @see. Por ejemplo:

— usuario7294900
fuente