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!
@seeemMethodB's javadoc e referênciaMethodAporque é 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 ...Respostas:
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 :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.
fonte
@seetambém é útil para vincular alternativas a@Deprecatedmétodos.@seeé muito vago, para coisas obsoletas acho mais útil fazer algo mais explícito, como:@deprecated since X.Y.Z; use {@link #alternateMethod()} instead@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.
fonte
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 teriajavadocseçã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:
@seefonte
@inheritDoccopia a documentação de outro local. Imagino que descrever detalhes em vez de adicionar perfumarias tem sua utilidade?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@inheritDoce 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.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
fonte