How to write Javadoc of properties?

Question

I often find myself with a dilemma when writing javadoc for properties/members of a "simple" POJO class holding only properties and getters and setters (DTO-style)....

1) Write javadoc for the property
or...
2) Write javadoc for the getter

If I write javadoc for the property, my IDE (Eclipse) will (naturally) not be able to display this when I later access the POJO via code completion. And there is no standard javadoc tag that lets me link the getter-javadoc to the actual property javadoc.

An example:

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

So, basically it would be interesting to hear how others go about for having your Eclipse IDE display the javadoc property description for your getters - without having to duplicate the javadoc comment.

As of now I'm considering making my practise to only document the getters and not the properties. But it doesn't seem like the best solution...

Answer 1

You can include private members while generating Javadocs (using -private) and then use @link to link to that fields property.

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

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

Alternatively, if you do not want to generate the Javadoc for all private members, you can have a convention to document all getters and use @link on 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;
    }
}