How to write javadoc properties?

Question

I often encounter a dilemma when writing javadoc for properties / members of a "simple" POJO class containing only properties and getters and setters (DTO style) ....

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

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

Example:

public class SomeDomainClass { /** * The name of bla bla bla */ private String name; /** * @return INSERT SOME SMART JAVADOC TAG LINKING TO name javadoc */ public String getName() { return name; } 

So basically it would be interesting to hear how others make your Eclipse environment display a description of the javadoc property for your getters - without duplicating the javadoc comment.

At the moment, I am considering using my practice only for documenting getters, not for properties. But this does not seem to be the best solution ...

Answer 1

You can include private members when generating Javadocs (using -private), and then use @link to refer to this property of the fields.

 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 Javadoc for all private members, you can have an agreement to document all recipients 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

I do both, which contributes to Eclipse autocomplete.

First, I document the property:

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

Then I copy and paste this into the getter:

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

With eclipse, @return statements are autocomplete - so I add the word "Gets", the lowercase "t" and copy the sentence in lowercase "t". Then I use @return (with Eclipse autocomplete), insert the sentence, and then delay T in return. Then it 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 this documentation to the installer:

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

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

 /** * 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 am done. In my opinion, this template makes it much easier, ultimately, not only reminding yourself what the property means by repeating, but also making it easy to add additional comments to the recipient and setter if you want to add side effects (such as the absence of null properties, rotation strings in uppercase, etc.). I researched the creation of the Eclipse plugin for this purpose, but I could not find the appropriate extension point for JDT, so I gave up.

Please note that the sentence may not always begin with T - it only the first letter should be uncapitalized / recapitalized when pasted.

Answer 3

Lombok is a very convenient library for such tasks.

 @Getter @Setter public class Example { /** * The account identifier (ie 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 creates a getter method for each private field and attaches javadoc to it.

PS . There are many interesting features in the library that you can check out.

Answer 4

I really think this is a problem, and the official Javadoc guide says nothing about it. C # can solve this in an elegant style using properties (I'm not C # code, but I really think this is a good feature).

But I have an assumption: if you need to explain what someString is, maybe it is "bad little" about your code. This may mean that you have to write SomeClass to enter someString, so you would explain what someString is in the SomeClass documentation, and that’s why you don’t need javadocs in getter / setter.