Eu quero escrever Javadoc de maneira SECA. Mas o documento da Oracle sobre Javadoc diz que escreva a mesma coisa novamente no comentário do método de sobrecarga. Não posso evitar a repetição?
Eu quero escrever Javadoc de maneira SECA. Mas o documento da Oracle sobre Javadoc diz que escreva a mesma coisa novamente no comentário do método de sobrecarga. Não posso evitar a repetição?
Respostas:
Aplico {@inheritDoc}diretivas aqui e ali nos comentários do Javadoc ao substituir métodos de superclasses ou implementar métodos definidos por interface.
Isso funciona bem para mim, pelo menos, evita repetições no código-fonte, e você ainda pode adicionar informações específicas ao comentário Javadoc específico, se houver necessidade. Eu não considero o fato de que o próprio comentário do Javadoc é praticamente inexistente quando tudo o que é necessário em um IDE decente é passar o mouse sobre o nome do identificador associado para obter o Javadoc renderizado com referências e tudo.
O objetivo da documentação é iluminar os futuros usuários de um item. Isso se deve em parte à conveniência do autor, para que ele não precise ser contatado sempre que alguém não puder descobrir como a coisa funciona. Principalmente, porém, é para o benefício das pessoas que precisam usar ou apoiar a coisa.
Como tal, o ponto deve ser a clareza, em oposição à conveniência do autor. Você não pode esperar que as pessoas pesquisem a documentação da API porque você estava com preguiça de se repetir. Suck it up - Javadoc será repetitivo.
Dito isto, não há razão, se você for esperto, não poderá escrever um programa que cole comentários em seu código com base em marcadores ou em outros critérios. Pode ser mais problema do que vale a pena. Ou não.