There are 3 places where we can find a user-written description about a property:
the field's javadoc comment
the getter's javadoc return tag value
the getter's javadoc comment
Usually, the description of the field, if present, is worded in a more suitable way than the description of the getter: "The foo of this bar" VS "Gets the foo of this bar".
Similarly, the @return tag of the javadoc of the getter is usually more suitable than the method description.
For this reason, I believe it would be nice to get the information from the first available one of these 3 places, in the order they are listed above.
There are 3 places where we can find a user-written description about a property:
Usually, the description of the field, if present, is worded in a more suitable way than the description of the getter: "The foo of this bar" VS "Gets the foo of this bar". Similarly, the
@returntag of the javadoc of the getter is usually more suitable than the method description.For this reason, I believe it would be nice to get the information from the first available one of these 3 places, in the order they are listed above.