Uso de @see em JavaDoc?

110

Quando devo usar @seepara lidar com JavaDocs? Qual é o seu uso?

Por exemplo, se MethodAas chamadas MethodB, em seguida, eu tenho que colocar @seeem MethodB's javadoc e referência MethodAporque é isso que chamou, ou eu tenho que colocar uma referência a MethodBpartir MethodAporque ele está chamando. Eu li coisas sobre @seeno site da Oracle e me parece incrivelmente vago, diz que significa "veja também", mas não exatamente o que isso significa!

java methods javadoc

— Jeff
fonte

4

colocar @seeem MethodB's javadoc e referência MethodAporque é isso que o chamou -> Como seria sempre possível conhecer todos os métodos que exigem um de seus métodos? Mesmo que isso seja possível (digamos, um método privado usado apenas uma vez) vincular do receptor ao chamador soa no mínimo estranho ...

— Mr_and_Mrs_D

1

Significa o que geralmente significa em inglês: oxforddictionaries.com/us/definition/american_english/see (definição 1.4)

— stackexchanger

119

Sim, é bastante vago.

Você deve usá-lo sempre que para leitores da documentação de seu método, pode ser útil examinar também algum outro método. Se a documentação do seu método A diz "Funciona como o método B, mas ...", então você certamente deve colocar um link. Uma alternativa para @seeseria a {@link ...}tag inline :

/**
 * ...
 * Works like {@link #methodB}, but ...
 */

Quando o fato de que o método A chama o método B é um detalhe de implementação e não há uma relação real de fora, você não precisa de um link aqui.

— Paŭlo Ebermann
fonte

13

@seetambém é útil para vincular alternativas a @Deprecatedmétodos.

— Mauve Ranger

1

@MauveRanger Como @seeé muito vago, para coisas obsoletas acho mais útil fazer algo mais explícito, como:@deprecated since X.Y.Z; use {@link #alternateMethod()} instead

— Christopher

10

@see é útil para obter informações sobre métodos / classes relacionados em uma API. Ele produzirá um link para o método / código referenciado na documentação. Use-o quando houver um código relacionado que possa ajudar o usuário a entender como usar a API.

— Rob Dawson
fonte

9

Um bom exemplo de uma situação em que @seepode ser útil seria implementar ou substituir um método de interface / classe abstrata. A declaração teria javadocseção detalhando o método e o método substituído / implementado poderia usar uma @seetag, referindo-se à base.

Pergunta relacionada: Escrevendo javadoc adequado com @see?

Documentação do Java SE: @see

— AtomHeartFather
fonte

2

não fui eu, mas provavelmente foi porque temos @inheritDoc docs.oracle.com/javase/6/docs/technotes/tools/solaris/…

1

a documentação do java para @see é realmente boa. deve ser o primeiro.

— dok

2

@vaxquis @inheritDoccopia a documentação de outro local. Imagino que descrever detalhes em vez de adicionar perfumarias tem sua utilidade?

— Nielsvh 01 de

@Nielsvg esta resposta menciona isso the overridden/implemented method could use a @see tag, referring to the base one.- e é exatamente @inheritDocpara isso que serve; IMO é melhor incluir a descrição da classe base literalmente por meio de @inheritDoc e complementá-la conforme necessário, do que se referir a ela por @see- consulte (sic!) Stackoverflow.com/questions/11121600/… ; muitos desenvolvedores (inclusive eu) preferem ter todos os detalhes de implementação em um só lugar, em vez de uma cadeia interminável de links ascendentes que levam para cima por uma hierarquia de herança.

2

Eu uso @see para anotar métodos de uma classe de implementação de interface onde a descrição do método já é fornecida no javadoc da interface. Quando fazemos isso, noto que o Eclipse puxa a documentação da interface mesmo quando estou procurando o método na referência de implementação durante a conclusão do código

— Maruthi
fonte