¿Cómo escribir Javadoc de propiedades?

A menudo me encuentro con un dilema al escribir javadoc para propiedades / miembros de una clase POJO "simple" que contiene solo propiedades y captadores y definidores (estilo DTO) ...

1) Escriba javadoc para la propiedad
o ...
2) Escriba javadoc para el captador

Si escribo javadoc para la propiedad, mi IDE (Eclipse) (naturalmente) no podrá mostrar esto cuando luego acceda al POJO mediante la finalización del código. Y no hay una etiqueta javadoc estándar que me permita vincular el getter-javadoc con la propiedad real javadoc.

Un ejemplo:

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

Entonces, básicamente, sería interesante escuchar cómo otros hacen que su Eclipse IDE muestre la descripción de la propiedad javadoc para sus captadores, sin tener que duplicar el comentario javadoc.

A partir de ahora, estoy considerando hacer mi práctica para documentar solo los captadores y no las propiedades. Pero no parece la mejor solución ...

Puede incluir miembros privados mientras genera Javadocs (usando -private) y luego usar @link para vincular a esa propiedad de campos.

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

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

Alternativamente, si no desea generar el Javadoc para todos los miembros privados, puede tener una convención para documentar todos los captadores y usar @link en los configuradores.

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

Lombok es una biblioteca muy conveniente para tales tareas.

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

¡Eso es todo lo que necesitas! los@Getter anotación crea un método de obtención para cada campo privado y le adjunta el javadoc.

PD : la biblioteca tiene muchas características interesantes que es posible que desee consultar

Hago ambas cosas, ayudado por el autocompletado de Eclipse.

Primero, documenté la propiedad:

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

Luego, copio y pego esto en el getter:

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

Con eclipse, las sentencias @return se autocompletan, por lo que agrego la palabra Gets, pongo la "t" en minúscula y copio la oración con la "t" minúscula. Luego uso @return (con autocompletar Eclipse), pego la oración y luego en mayúscula la T en la devolución. Entonces se ve así:

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

Finalmente, copio esa documentación al colocador:

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

Luego, lo modifico y con el autocompletado de Eclipse puede obtener no solo la etiqueta @param sino también el nombre del 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;
}

Entonces, he terminado. En mi opinión, esta plantilla hace que sea mucho más fácil, a largo plazo, no solo recordarse a sí mismo lo que significa la propiedad a través de la repetición, sino que también facilita agregar comentarios adicionales al getter y setter si desea agregar side efectos (como no permitir propiedades nulas, convertir cadenas a mayúsculas, etc.). Investigué la creación de un complemento de Eclipse para este propósito, pero no pude encontrar el punto de extensión apropiado para el JDT, así que me rendí.

Tenga en cuenta que es posible que la oración no siempre comience con una T; es solo que la primera letra debe estar sin mayúscula / recapitalizada al pegar.

Realmente creo que es un problema y la guía oficial de Javadoc no dice nada al respecto. C # puede resolver esto de una manera elegante con el uso de Propiedades (no codifico en C #, pero realmente creo que es una buena característica).

Pero tengo una suposición: si necesita explicar qué es someString, tal vez sea un `` pequeño error '' sobre su código. Puede significar que debería escribir SomeClass para escribir someString, por lo que explicaría qué es someString en la documentación de SomeClass, y así los javadocs en getter / setter no serían necesarios.