Javadoc @see ou {@link}?

Alguém poderia me dizer a diferença entre javadoc @see e {@link} ?

Ou melhor, quando usar qual deles?

As diretrizes oficiais sobre isso são bem claras.

As diferenças funcionais são:

  • {@link} é um link in-line e pode ser colocado onde você quiser
  • @see cria sua própria seção

Na minha opinião, {@link} é melhor usado quando você literalmente usa um nome de class, campo, construtor ou método em sua descrição. O usuário poderá clicar no javadoc do que você vinculou.

Eu uso a anotação @see em 2 casos:

  • Algo é muito relevante, mas não mencionado na descrição.
  • Eu me refiro à mesma coisa várias vezes na descrição, e ela é usada como um substituto para vários links para o mesmo.

Eu baseei essa opinião na verificação aleatória de documentação para uma grande variedade de coisas na biblioteca padrão.

@see cria uma linha isolada nos Javadocs. {@link} é para incorporar no texto.

Eu uso @see quando é uma entidade relacionada, mas não me refiro a ela no texto expositivo. Eu uso links dentro de texto quando há um acoplamento forte, ou (eu sinto) é provável que o leitor se beneficie da dica de navegação, por exemplo, você precisará referenciá-lo diretamente.

Há outra referência (seção depreciativa) em que os mesmos documentos oficiais preferem {@link} sobre @see (desde o Java 1.2):

Para o Javadoc 1.2 e posterior, o formato padrão é usar a tag @deprecated e a tag {@link} in-line. Isso cria o link in-line, onde você quiser. Por exemplo:

Para o Javadoc 1.1, o formato padrão é criar um par de tags @deprecated e @see. Por exemplo: