Detalhes da diferença entre @see e @inheritDoc

87

Eu examinei a referência JavaDoc e, embora eu entenda a diferença básica entre @see(vários links) e {@inheritDoc}(exportação do comentário JavaDoc da superclasse), preciso de esclarecimento sobre como as coisas realmente são implementadas.

No IDE Eclipse, quando eu seleciono “Gerar comentários de elemento” para o método herdado (da interface ou substituição de toString () e assim por diante), ele cria o comentário a seguir

/* (non-Javadoc)
 * @see SomeClass#someMethod()
 */

Se eu sou obrigado a produzir JavaDoc eu deveria deixar por isso mesmo, substitua @seecom {@inheritDoc}, ou transformá-lo em bona fide JavaDoc como tal:

/**
 * {@inheritDoc}
 */

E quando eu fizer isso, ainda devo manter o sinalizador de método class #?

java javadoc comments theUg
fonte

Respostas:

143

Em primeiro lugar, você deve remover o modelo de eclipse original porque ele é apenas um lixo barulhento. Coloque documentos significativos ou não coloque nada. Mas a reformulação inútil do óbvio usando modelos IDE apenas confunde o código.

Segundo, se você é obrigado a produzir javadoc, então você tem de fazer o comentário começo com /**. Caso contrário, não é javadoc.

Por último, se você estiver substituindo, você deve usar @inheritDoc(supondo que deseja adicionar aos documentos originais, como @seh observou em um comentário, se você deseja apenas duplicar os documentos originais, não precisa de nada). @seesó deve ser usado para fazer referência a outros métodos relacionados.

Jtahlborn
fonte
75
Você só deve usar @inheritDocse pretende adicionar à documentação original da superclasse. Se você simplesmente deseja que seja duplicado, o Javadoc já fará isso, observando que a documentação da superclasse se aplica ao método sobrescrito da subclasse porque a subclasse não forneceu documentação adicional.
seh
4
Eu gerei os documentos com e sem @inheritDoce não vejo nenhuma diferença. Mesmo sem o @inheritDoc, vejo que o Javadoc da classe derivada foi anexado à classe base.
randominstanceOfLivingThing
Eu vim aqui porque o checkstyle reclama "o método não parece ser projetado para extensão". Uma boa ideia pode ser usar @inheritDoce, em seguida, adicionar alguma documentação específica de implementação, por exemplo, como ele implementa / sobrescreve o método pai e, especialmente, POR QUE o faz dessa maneira.
Ben