Cómo escribir Javadoc de propiedades?

Question

A menudo me encuentro con un dilema al escribir javadoc para 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) javadoc para el captador

Si escribo javadoc para la propiedad, mi IDE (Eclipse) será (natural) no sea capaz de mostrar esta tarde cuando accedo a la vía código POJO terminación. 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; 
    } 

Así que, básicamente, sería interesante escuchar cómo otros andan por tener su IDE Eclipse mostrar la descripción de la propiedad javadoc para sus captadores - sin tener que duplicar el comentario Javadoc.

Por el momento, 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

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

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

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

Como alternativa, si no desea generar el Javadoc para todos los miembros privados, puede tener una convención para documentar todos los captadores y utilizar a los organismos de enlace @.

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 2

Hago ambas cosas, con la ayuda de la autocompleta de Eclipse.

En primer lugar, tengo que documentar la propiedad:

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

Entonces, puedo copiar y pegar esto al comprador:

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

con Eclipse, declaraciones @return tienen un autocompletar - así, añado la palabra Obtiene, minúscula la "t", y copia 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. A continuación, se ve así:

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

Por último, copio que la documentación de la incubadora:

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

Entonces, modificarlo y con Eclipse autocompletar puede obtener no sólo 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; 
} 

Luego, 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 3

Realmente creo que es un problema y el Javadoc guide oficial 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 alguna cadena, tal vez es un `` mal 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 captador para cada campo privado y adjunta el javadoc.

PS: La biblioteca tiene muchas características interesantes que usted podría querer a la comprobación