practices - javadoc eclipse

Cómo escribir Javadoc de propiedades?

Question

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

1) Escriba javadoc para la propiedad
o...
2) Escribir javadoc para el getter

Si escribo javadoc para la propiedad, mi IDE (Eclipse) (por supuesto) no podrá mostrar esto cuando más tarde 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 para que su Eclipse IDE muestre la descripción de la propiedad javadoc para sus usuarios, sin tener que duplicar el comentario de javadoc.

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

Answer 1

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 al getter:

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

Con eclipse, las declaraciones @return tienen una función de autocompletar, así que agrego la palabra Obtiene, minúscula la "t" y copio la oración con la "t" minúscula. Luego uso @return (con autocompletar Eclipse), pego la oración y luego mayúsculo 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 Eclipse Autocomplete 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 la larga, no solo recordar lo que significa la propiedad a través de la repetición, sino que también hace que sea más fácil agregar comentarios adicionales al captador y al colocador si desea agregar lado efectos (como no permitir propiedades nulas, convertir cadenas en mayúsculas, etc.). Investigué haciendo un plugin de Eclipse para este propósito pero no pude encontrar el punto de extensión apropiado para el JDT, así que me di por vencido.

Tenga en cuenta que la oración puede no siempre comenzar con una T, es solo la primera letra que debe descapitalizarse / recapitalizarse al pegar.

Answer 2

Puedes incluir miembros privados mientras generas Javadocs (usando -private) y luego usar @link para enlazar a esa propiedad de los 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 getters y usar @link en 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;
    }
}

Answer 3

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

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

Answer 4

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! La anotación @Getter crea un método getter para cada campo privado y adjunta el javadoc a él.

PD : la biblioteca tiene muchas características geniales que tal vez quieras pagar