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

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