30

I want Eclipse to automatically generate Javadoc comments for my getter and setter methods based on the previously defined comments for the fields. How can I achieve this?

Background: A policy in our company is to comment every method and field (even if they have self-explanatory names). So I have to do redundant work by describing the fields and describing the getters / setters again.

Example:

/**
 * name of the dynamic strategy
 */
private String dynName;

/**
 * get the name of the dynamic strategy
 * @return
 */
public String getDynName() {
    return dynName;
}

Searching the web showed that I'm not the only one with the problem - but I couldn't find any solutions. I checked out http://jautodoc.sourceforge.net/ but seems like it is not capable of doing this.

räph
  • 3,634
  • 9
  • 34
  • 41
  • How useful is that? You can type `F3` on `dynName` and it would take you there. Also refactoring become hard, if not impossible. – fastcodejava May 27 '10 at 08:07

9 Answers9

15

JAutodoc since ver 1.6 (1 year after the question) has a new option "[G,S]etter from field comment", which does exactly what you want.

This is a quite handy feature. Field comments are usually not included in the final Javadoc HTML because they might/should be private members (generating Javadoc for every private member is not good either), so the comments would be completely lost without it!

I wonder if this Q/A thread might have motivated the author to implement this nice feature.

hideaki
  • 151
  • 1
  • 2
5

I finally found a solution (or at least a workaround) myself. I read about Spoon on SO. It's an Java program processor which allows to read and modify java source files. It can even be used as Eclipse Plugin or Ant/Maven script.

Everything you have to do, is to extend the AbstractProcessor, which will process a method. If the method name starts with get/set it looks for the corresponding field, extracts its comment and replaces or extends the accessors comment with it.

I have a little ant script, which takes all my sources and processes them.

Something integrated in eclipses code templates would be of course more convenient, but for now this way is ok!

räph
  • 3,634
  • 9
  • 34
  • 41
4

I agree that duplicating documentation is a problem. What about documenting the private variable and then providing a link to that documentation in the accessor methods?

(Obviously, the following solution is for very simple accessor methods. You don't really want to expose private variable documentation in your API, especially if your accessor method actually does something noteworthy.)

public class MyBean {

/**
 * The names description
 */
private String name;

/**
 * @return {@link #name}
 */
public String getName() {
    return name;
}

/**
 * @param name {@link #name}
 */
public void setName(String name) {
    this.name = name;
}
}

Note that, if you're using Eclipse, you may need to enable referencing private variables in your javadoc as follows:

  • Right-click on project in Package Explorer and select Properties
  • Collapse the Java Compiler node and select Javadoc
  • Select enable project specific settings and under Only consider members as visible as: select private

    I suspect search performance will be affected, but I haven't yet used tested by how much.

    • Stephen Paul
    • 37,253
    • 15
    • 92
    • 74
    4

    if you use Eclipse's tool to override/implement methods... from the source menu, there is an option to automatically generate javadoc comments. there are comment templates that you can modify in preferences->java->code style -> code templates -> comments.

    akf
    • 38,619
    • 8
    • 86
    • 96
    • 1
      yes, but the only variable available for the templates is ${bare_field_name}, which is the name of the field - and not its description in the comment – räph Jun 15 '09 at 13:31
    • 1
      it is a start. you will ultimately need to provide this description somewhere. – akf Jun 15 '09 at 13:34
    • 1
      right, I wanted to comment the field and then let eclipse generate the getter/setter with comments based on the field comment. – räph Jun 15 '09 at 13:37
    2

    If you had a macro language, you could write a function like "open a popup that allows me to type in some text, then generates the getter and setter, including its javadoc, based on templates".

    Eclipse has actually no real support for such a macro language, but maybe you could anyway have a look at : Is there a Macro Recorder for Eclipse?

    If you're not reluctant to switch between eclipse and another tool, then you could try JEdit (jedit.org) that includes powerful beanshell macro language. In such a way, you can have eclipse & jedit opened, you drag&drop the file you want to process from eclipse to jedit, you use jedit macro power, then save the file and finally refresh file within eclipse.

    It's a bit annoying, but for some processings that's the way I have successfully adopted.

    Community
    • 1
    • 1
    Michael Zilbermann
    • 1,398
    • 9
    • 19
    • I will take a look at the macro thing. Working with eclipse and jedit is kind of cumbersome. I think then it is faster for me to copy the comments by hand! – räph Jun 16 '09 at 05:15
    1

    IMHO If the comments can be automatically generated, they don't add much value.
    If you called your method getDynamicStrategyName() you won't need to comment it as the name contains all the information you would have put in the comment.

    Peter Lawrey
    • 525,659
    • 79
    • 751
    • 1,130
    • as I said, it's an requirement, even if the names are easy understandable. so I can't do much about it. the comments are of course not really generated - you enter the comment for the field - and eclipse should use that comment for the getter/setters too! it's not always possible to put every needed information into the fieldname (unless you want to have really long names...). – räph Jun 17 '09 at 14:40
    1

    I use Eclipse Luna 4.4.

    • Choose menu Window \ Preferences, choose Java \ Code Style \ Code Templates. Choose Section Comments \ Getters | Setters, press button Edit....

    enter image description here

    • There are many existing variables for you, use button Insert Variable...

      enter image description here

    • Edit your comment format, then press button Apply, then press OK to finish.

    Vy Do
    • 46,709
    • 59
    • 215
    • 313
    • that's fine, but in the last step, the question is which variable could be used? If I need the comment from the field - is there a variable for this purpose? – räph May 18 '15 at 06:11
    • 1
      can this also be applied to add comments to existing code? – Raphael Roth Jun 10 '15 at 13:20
    1

    The JavadocWriter plugin for IntelliJ IDEA says it does a "smart copy the javadoc from field to accessor". Caveat utilitor: I haven't tried the plugin myself, and it hasn't been updated in 3 years.

    flicken
    • 15,443
    • 4
    • 29
    • 29
    0

    Actually JAutodoc can generate comments for getter/setter based on field comments. You have to check option "Create comment from element name", see http://jautodoc.sourceforge.net/ for documentation.

    pawelsto
    • 75
    • 5