How to write Javadoc of properties?

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

Solution 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

Solution 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.