Como escrever Javadoc de propriedades?

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 ...

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;
    }
}

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

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.

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.