8

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?

Jeff Axelrod
  • 27,676
  • 31
  • 147
  • 246
  • Related: http://stackoverflow.com/questions/996093/how-to-automatically-generate-comments-for-getter-setter-based-on-field-comments – Jeff Axelrod May 29 '12 at 19:23

3 Answers3

3

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.

lrxw
  • 3,576
  • 7
  • 32
  • 46
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.)

Dave Newton
  • 158,873
  • 26
  • 254
  • 302
  • 2
    In Eclipse, other than including field documentation or `@See` in the setter/getter, wouldn't I have to first navigate to the setter method, then hover over the field reference in order to access the javadoc? Ideally, I'd just hover over the getter/setter and find out what the heck I intended to use the field for. :) – Jeff Axelrod May 29 '12 at 19:33
  • @JeffAxelrod The only other options (w/o any actual research) would be to just use getters and setters, or name them better. – Dave Newton May 29 '12 at 19:35
1

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.

Michael Scheper
  • 6,514
  • 7
  • 63
  • 76