Como escrever Javadoc de propriedades?

93

Muitas vezes me encontro com um dilema ao escrever javadoc para propriedades / membros de uma classe POJO "simples" contendo apenas propriedades e getters e setters (estilo DTO) ....

1) Escreva javadoc para a propriedade
ou ...
2) Escreva javadoc para o getter

Se eu escrever javadoc para a propriedade, meu IDE (Eclipse) não será (naturalmente) capaz de exibir isso quando eu acessar o POJO posteriormente por meio do autocompletar de código. E não há uma tag javadoc padrão que me permita vincular o getter-javadoc ao javadoc da propriedade real.

Um exemplo:

public class SomeDomainClass {

  /**
   * The name of bla bla bla
   */
  private String name;

  /**
   * @return INSERT SOME SMART JAVADOC TAG LINKING TO name's javadoc
   */
  public String getName() {  
    return name;  
  }  

Portanto, basicamente, seria interessante ouvir como os outros fazem para que seu IDE Eclipse exiba a descrição da propriedade javadoc para seus getters - sem ter que duplicar o comentário javadoc.

No momento, estou pensando em fazer minha prática apenas documentar os getters e não as propriedades. Mas não me parece a melhor solução ...


fonte
1
Discussão interessante sobre isso aqui: stackoverflow.com/questions/1028967/… . A resposta aceita aborda o que você perguntou sobre Eclipse / javadoc.
b.roth
Parece que eles concluíram com o que eu estava considerando ... escrever propriedade javadoc apenas nos getters.
Eu encontrei uma maneira de fazer isso com anotações que funcionam no eclipse e podem até ser coletadas em tempo de execução, seria uma opção?
Aquarius Power
membros privados precisam do javadoc?
Cherit
O nome de bla bla bla: melhor exemplo
Rodrigo Espinoza

Respostas:

75

Você pode incluir membros privados ao gerar Javadocs (usando -private) e, em seguida, usar @link para vincular a essa propriedade de campos.

public class SomeDomainClass {
    /**
     * The name of bla bla bla
     */
    private String name;

    /**
     * {@link SomeDomainClass#name}
     */
    public String getName() {
        return name;
    }
}

Alternativamente, se você não deseja gerar o Javadoc para todos os membros privados, você pode ter uma convenção para documentar todos os getters e usar @link nos setters.

public class SomeDomainClass {
    private String name;

    /**
     * The name of bla bla bla
     */
    public String getName() {
        return name;
    }

    /**
     * {@link SomeDomainClass#getName}
     */
    public void setName(String name) {
        this.name = name;
    }
}
Chandra Sekar
fonte
2
Eu experimentei as tags @link e @see .. Mas ... pelo menos o Eclipse não exibe isso corretamente. O Eclipse exibe o link como um ... (drumroll) .... link .. que será necessário clicar para ver o conteúdo. Quero ser capaz de ativar o
13
@Kenny - não modele suas práticas JavaDoc a partir do POV de usabilidade do Eclipse. Faça isso a partir do ponto de vista de obter a saída JavaDoc correta (ou suficientemente boa). Os IDEs mudam, e o que pode ser deficiente hoje pode ser resolvido amanhã (ou você pode realmente mudar os IDEs completamente.)
luis.espinal
1
@luis @linksignifica um link que deve ser clicado para ver o javadoc real. Não é um problema de usabilidade do Eclipse, é a solução errada para fornecer javadocs fáceis de usar.
NateS de
4

O Lombok é uma biblioteca muito conveniente para essas tarefas.

@Getter
@Setter
public class Example {
    /**
     * The account identifier (i.e. phone number, user name or email) to be identified for the account you're
     * requesting the name for
     */
    private String name;
}

Isso é tudo o que você precisa! A @Getteranotação cria um método getter para cada campo privado e anexa o javadoc a ele.

PS : A biblioteca tem muitos recursos interessantes que você pode querer verificar

Amanuel Nega
fonte
3

Eu faço ambos, auxiliado pelo autocomplete do Eclipse.

Primeiro, eu documento a propriedade:

/**
 * The {@link String} instance representing something.
 */
private String someString;

Em seguida, copio e colo no getter:

/**
 * The {@link String} instance representing something.
 */
public String getSomeString() {
    return someString;
}

Com o eclipse, as instruções @return têm um preenchimento automático - então, adiciono a palavra Gets, minúsculo o "t" e copio a frase com o "t" minúsculo. Em seguida, uso @return (com preenchimento automático do Eclipse), colo a frase e maiúsculo no retorno. Então, fica assim:

/**
 * Gets the {@link String} instance representing something.
 * @return The {@link String} instance representing something.
 */
public String getSomeString() {
    return someString;
}

Finalmente, copio essa documentação para o configurador:

/**
 * Gets the {@link String} instance representing something.
 * @return The {@link String} instance representing something.
 */
public void setSomeString(String someString) {
    this.someString = someString;
}

Então, eu o modifico e com o autocomplete do Eclipse você pode obter não apenas a tag @param, mas também o nome do parâmetro:

/**
 * Sets the {@link String} instance representing something.
 * @param someString The {@link String} instance representing something.
 */
public void setSomeString(String someString) {
    this.someString = someString;
}

Então, estou feito. Na minha opinião, este modelo torna muito mais fácil, a longo prazo, não apenas lembrar a si mesmo o que a propriedade significa por meio da repetição, mas também torna mais fácil adicionar comentários adicionais ao getter e setter se você quiser adicionar lado efeitos (como não permitir propriedades nulas, transformar strings em maiúsculas, etc.). Eu investiguei a criação de um plug-in Eclipse para esse propósito, mas não consegui encontrar o ponto de extensão apropriado para o JDT, então desisti.

Observe que a frase nem sempre pode começar com um T - é apenas a primeira letra que deve ser sem maiúscula / recapitalizada ao colar.

MetroidFan2002
fonte
23
Copiar / colar é ruim ... e demorado. Essas etapas parecem muito trabalhosas e, se o javadoc mudar, você terá 3 locais diferentes para atualizar. Eu não acho que um plugin justificaria isso também ... pelo menos, então o plugin teria que, por exemplo, considerar a propriedade javadoc como mestre e então sobrescrever os getters (e setters). O que desejo realizar é escrever o javadoc em um único lugar e, em seguida, fazer com que os getters e os javadocs de propriedade assumam a mesma descrição ...
Normalmente, as propriedades não mudam com tanta frequência. E as operações de copiar e colar, com o preenchimento automático do Eclipse, levam menos de 30 segundos depois que a propriedade Javadoc é construída.
MetroidFan2002
4
Não estou convencido ... A introdução deste tipo de esquema de copiar / colar é, IMHO, obrigada a levar a inconsistências. Tenho muito pouca fé em outros cozinheiros (ou em mim) editando o código mais tarde. Além disso, pelo menos se você não tiver um design inicial completo, as propriedades do javadoc geralmente estão sujeitas a alterações, pelo menos durante uma fase experimental / de design. E o javadoc será de melhor qualidade se escrito quando o código estiver fresco na mente ... Desculpe se pareço um chorão ;-)
1
Desculpe, mas as propriedades de edição levam a inconsistências - de qualquer maneira que você jogue, o Javadoc tende a cair no esquecimento, a menos que seja vigorosamente mantido de alguma forma. Mesmo que houvesse uma maneira fácil de expor a propriedade javadoc, é provável que a propriedade javadoc em si não seja atualizada. É realmente uma questão de convenções de codificação da equipe, etc, e revisões de código, coisas assim - boa sorte para você, é assim que eu faço, então não me esqueço.
MetroidFan2002
@Metroid - a menos que seja vigorosamente mantido de alguma forma - bem, é suposto que seja mantido vigorosamente se for tratado como parte do próprio código-fonte. E não tratar os comentários Javadoc (e seus equivalentes em outras linguagens) como parte intrínseca do código, embora infelizmente seja a prática padrão, é a raiz de muitos males. O pior comentário é aquele que ficou desatualizado. Na melhor das hipóteses, eles desaceleram os programadores de obter controle sobre o código (já que eles precisam constantemente revalidar e aceitar / rejeitar comentários desatualizados). Na pior das hipóteses, eles fornecem informações que apresentam erros e apresentam erros.
luis.espinal
0

Eu realmente acho que é um problema e o guia Javadoc oficial não diz nada sobre isso. C # pode resolver isso de uma forma elegante com o uso de Propriedades (não codifico em C #, mas realmente acho que é um bom recurso).

Mas eu tenho um palpite: se você precisa explicar o que é someString, talvez seja um `` pequeno ruim '' sobre o seu código. Isso pode significar que você deve escrever SomeClass para digitar someString, então você explicaria o que é someString na documentação de SomeClass, e apenas para que os javadocs em getter / setter não sejam necessários.

Leonardo Leite
fonte
1
Sobre o não uso apropriado de strings no código, verifique `` Evite strings onde outros tipos são mais apropriados '' no livro Effective Java.
Leonardo Leite