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

• b.roth: Interesting discussion on this here: stackoverflow.com/questions/1028967/…. The accepted answer addresses what you asked about Eclipse / javadoc.
• user274360: Seems like they concluded with what I was considering... write property javadoc only in the getters.
• Aquarius Power: I found a way to do this with annotations that work in eclipse and can even be collected at runtime, would that be an option?
• Tito: private members need javadoc ?
• Rodrigo Espinoza: The name of bla bla bla : best example

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

• user274360: I have experimented with both @link and @see tags.. But... at least Eclipse does not display this properly. Eclipse displays the link as a ...(drumroll) .... link.. that one will have to click in order to see the contents. I want to be able to activate code completion (or by mouse over) get the javadoc for a property when I actually are browsing a getter...
• luis.espinal: @Kenny - don't model your JavaDoc practices from the POV of Eclipse' usability. Do it from the POV of getting the correct (or sufficiently good-enough) JavaDoc output. IDEs change, and what might be deficient today might be addressed tomorrow (or you might actually change IDEs completely.)
• NateS: @luis @link means a link which has to be clicked to see the actual javadoc. It's not an Eclipse usability issue, it's the wrong solution for providing javadocs that are easy to use.

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.

• user274360: Copy/paste is evil... and time consuming. These steps look like a lot of work, and if the javadoc changes you'll have 3 different places to update. I don't think a plugin would justify this either... atleast, then the plugin would have to e.g. consider the property javadoc to be the master and then overwrite getters (and setters). What I want to accomplish is to write the javadoc in 1 single place, and then have both getters and property javadocs assume the same description...
• MetroidFan2002: Typically, properties don't change all that often. And the copy and paste operations, with Eclipse's autocomplete, takes less than 30 seconds once the property Javadoc is constructed.
• user274360: I'm not convinced... Introduction of this type of copy/paste scheme is IMHO bound to lead to inconsistencies. I have too little faith in other cooks (or myself) editing the code later. Also, at least if you're not having a complete up-front design, javadoc properties is often subject to change, at least during a experimental/design phase. And javadoc will be of better quality if written when the code is fresh in mind... Sorry if I seem like a whiner ;-)
• MetroidFan2002: Sorry, but editing properties is bound to lead to inconsistencies - either way you play it, Javadoc tends to fall by the wayside unless it is vigorously maintained in some fashion. Even if there was an easy way to expose the property javadoc, it's just as likely that the property javadoc itself won't be updated. It's really a matter of the coding conventions of the team, etc, and code reviews, stuff like that - good luck to you, this is just the way I do it so I don't forget.
• luis.espinal: @Metroid - unless it is vigorously maintained in some fashion - well, it is supposed to be vigorously maintained if it is treated as part of the source code itself. And not treating Javadoc comments (and their equivalent in other languages) as intrinsic part of code, though sadly being the standard practice, it is the root of many evils. The worst comment is the one that has become out dated. At best, they slow down programmers from getting a grip on code (as they have to constantly revalidate and accept/reject outdated comment.) At worse, they give error-prone, bug-introducing info.

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.

• Leonardo Leite: About the no proper usage of strings in code, check ``Avoid strings where other types are more appropriate'' in the Effective Java book.