Suppose I have a property with an associated getter and setter (the property is not exposed directly)
Where should I describe the property?
- The field javadoc
- The getter javadoc
- The setter javadoc
Avoiding duplication would be nice (in case of any changes, I absolutely do not want to manually keep getter and setter descriptions in sync). However, documenting a private field doesn't feel right.
While often javadocs would be superfluous, there are times when clarification is appropriate. Imagine the property is some functional interface. In my case it's a Function. It's likely, for example, a maintainer would appreciate knowing what value is passed into the function so that they know how it can be handled (not just the value type). While you can try and describe it using the property's name alone, it can become a mouthful real quick.
Or imagine it's a Predicate. Now the maintainer will have to know not just what the input value represents, but also when the predicate is expected to return true.