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

Respuestas:

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