Javadoc @see ou {@link}?

184

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

Ou melhor, quando usar qual deles?

java javadoc som do membro
fonte

Respostas:

213

As diretrizes oficiais sobre isso são bastante claras.

As diferenças funcionais são:

  • {@link} é um link embutido 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 classe, campo, construtor ou método em sua descrição. O usuário poderá clicar no javadoc do que você vinculou.

Eu uso a @seeanotação em 2 casos:

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

Baseei essa opinião no check-out aleatório da documentação para uma grande variedade de coisas na biblioteca padrão.

MarioDS
fonte
3
O javadoc avisa que o @link é bastante intenso e deve ser usado apenas quando necessário.
Thomas
4
Para quem procura, você pode obter detalhes sobre isso (incluindo o aviso @linkno comentário acima) no guia Javadoc da Oracle .
Ash Ryan Arnwine
48

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

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

Dave Newton
fonte
3

Há uma outra referência (seção depreciação) mesmos documentos oficiais a preferir {@link}mais @see(desde 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ê desejar. Por exemplo:

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

user7294900
fonte