Can I avoid duplicating fields' Javadoc comments in getter/setter methods?

Question

I'd like to write my Javadoc comments once for each field and access the exiting field's Javadoc in the getter and setter methods.

I know there's the {@inheritDoc} tag for referencing the parent method's documentation, but I want to include the documentation of a field, which of course is not a parent method.

Is it possible to "don't repeat yourself" with Javadoc?

Answer 1

I add javadoc comments on my getters and add a {@link MyObject#get..()} on the field.

So its easy to read for the users of my API/object and I(or another developer) just have to hover over my private fields if I want to get more information.

Answer 2

Other than @see, not sure how.

But if you're generating internal documentation, you don't really need to document the getters/setters. If you're generating external documentation, you wouldn't document private properties anyway.

(Truth be told, at one point I had a rather spectacular set of scripts/etc. that would process Java source code and do magical things like this due to various limitations in the Java tool chain. I gave it up some time ago now that IDEs are much better, but there are some things, like weaving multiple files into single classes and whatnot that were really handy. Sort of like fake mixins, some doc magic, etc.)

(Actually, the Spoon project linked to is pretty similar to what I was doing, but pre-1.5.)

Answer 3

This kind of boilerplate can be avoided by using Project Lombok. Just document the field variable, even if it's private, and let Lombok annotations generate properly documented getters and setters.

For me, this benefit alone is worth the costs.