27

I am using Eclipse IDE for my Java Project.

I have one problem. I have the methods in my project which have the javadoc comments like as follows:

/**
 * Retruns the string representation of a input stream
 * @param in
 * @return
 * @throws IOException
 */
public static String getStringFromInputStream (InputStream in) throws IOException {
    StringBuffer out = new StringBuffer();
    byte[] b = new byte[4096];
    for (int n; (n = in.read(b)) != -1;) {
        out.append(new String(b, 0, n));
    }
    return out.toString();
}

Now I want to know that Is there any way by which whenever if I make changes in my method's signature, those changes reflect in the javadoc automatically.

Paŭlo Ebermann
  • 73,284
  • 20
  • 146
  • 210
Amit
  • 33,847
  • 91
  • 226
  • 299
  • 2
    Might be good to retitle this. There's no problem with javadoc as the title claims. Maybe something along the lines of "Refactoring from JavaDoc changes in Eclipse". I don't think you can do this without writing a plugin, btw. – Jonathon Faust Feb 14 '10 at 06:58
  • 1
    **This is still open to answer !!!!**. All answer refer to refactor option. But what if I added a new param or deleted a param from method signature. In that case, how to update the javadoc? – mtk Jan 30 '15 at 09:24
  • Guys check my answer for a workaround ! – mtk Jan 30 '15 at 09:30

6 Answers6

13

Eclipse provides fairly good options to ensure the correctness of javadoc besides the Rename refactor JesperE mentioned:

  • The Change method signature refactor operation also modifies javadoc (add/remove necessary tags). You should use this one or Rename to modify code which are already in use.
  • If you activate Add Javadoc tags on Preferences/Java/Editor/Typing page then Eclipse generates the correct javadoc stub after typing /** + Enter before a method.

You can also set compiler options to check javadoc missing tags on Preferences/Java/Compiler/Javadoc. In this case you get warnings from the compiler on missing/extra tags and you have quickfix (Ctrl+1) for fixing them. It is a good option to ensure the correctness of existing javadocs in the long run.

Csaba_H
  • 8,215
  • 1
  • 41
  • 42
4

I don't know about any way to automatically sync the Javadoc header, but if you rename a parameter using Ctrl-1 + Rename in file, the Javadoc header is appropriately renamed.

JesperE
  • 63,317
  • 21
  • 138
  • 197
3

Refactoring with the "Update references" option is not sufficient. You need to ensure that "Process Javadoc comments" is checked in Window->Preferences, Java->Compiler->Javadoc. Tweak the preference page like you prefer and it will work fine.

Mat
  • 31
  • 2
2

Just press ALT+SHIFT+j on the method name and delete the extra lines:

BEFORE:

/**
 * Copies all the details from the passed template into the passed new
 * header.
 *
 * @param pNewHeader
 */
private void doCopy(int pNewHeader, int pTemplate) {

AFTER:

/**
 * Copies all the details from the passed template into the passed new
 * header.
 *
 * @param pNewHeader   << DELETE
 */                    << DELETE
/**                    << DELETE
 * @param pNewHeader
 * @param pTemplate
 */
private void doCopy(int pNewHeader, int pTemplate) {
Yaza Fatutu
  • 21
  • 2
1

Press Atl+Shift+R and change

Amit
  • 33,847
  • 91
  • 226
  • 299
  • 1
    Only works with parameter names. Signature changes also include adding/removing parameters, changing the throws clause, etc. – whiskeysierra Feb 14 '10 at 23:57
  • 2
    Technically, this is just the command [for `Refactor` > `Rename`](http://www.n0sl33p.org/dev/eclipse_keys.html). – Pops Sep 08 '11 at 16:16
1

As I have commented the scenario, in which refactor won't work

All answer refer to refactor option. But what if I added a new param or deleted a param from method signature. In that case, how to update the javadoc?

There is a workaround I found, but yes it's still not a automated process and is not good for large number of changes.

The workaround is to,
1. remove the javadoc comment and make it plain comment i.e. update the /**' and change it to just/*'.
2. Now once again just above the method signature/declaration enter /** and press enter. It would re-populate the updated params and return info. Now just move the description lines from the older comment to the new.
3. You can use Alt + Up/Down arrows for achieving this.
4. Done delete the old javadoc comment after it's copied in correct place.

mtk
  • 13,221
  • 16
  • 72
  • 112
  • 1
    _"But what if I added a new param or deleted a param from method signature. In that case, how to update the javadoc?"_ — Csaba_H's answer addresses this; you use _Refactor_ > _Change Method Signature..._ and it will add and/or remove the param(s) on both the method signature _and_ the javadoc. – Stephen P Jul 16 '15 at 18:42