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

Answer 2

Lombok is a very convenient library for such tasks.

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

That is all you need! The @Getter annotation creates a getter method for each private field and attach the javadoc to it.

PS: The library has many cool features you might want to checkout

Answer 3

I do both, aided by Eclipse's autocomplete.

First, I document the property:

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

Then, I copy and paste this to the getter:

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

With eclipse, @return statements have an autocomplete - so, I add the word Gets, lowercase the "t", and copy the sentence with the lowercase "t". I then use @return (with Eclipse autocomplete), paste the sentence, and then uppercase the T in the return. It then looks like this:

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

Finally, I copy that documentation to the setter:

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

Then, I modify it and with Eclipse autocomplete you can get not only the @param tag but also the name of the parameter:

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

Then, I'm done. In my opinion, this templating makes it a lot easier, in the long run, to not only remind yourself what the property means through repetition, but also it makes it easier to add additional comments to the getter and setter if you want to add side effects (such as not allowing null properties, turning strings to uppercase, etc). I investigated making an Eclipse plugin for this purpose but I couldn't find the appropriate extension point for the JDT, so I gave up.

Note that the sentence might not always start with a T - it's just the first letter has to be uncapitalized/recapitalized in pasting.

Answer 4

I really think it's a problem and the official Javadoc guide does not tell anything about it. C# can solve this in an elegant fashion with the Properties usage (I don't code in C#, but I really think it's a nice feature).

But I have a guess: if you need to explain what someString is, maybe it is a ``bad small'' about your code. It can mean that you should write SomeClass to type someString, so you would explain what is someString in the SomeClass documentation, and just so the javadocs in getter/setter would be not necessary.