#1280 False Positive in UnusedImports when import used in javadoc

[Patrick McEvoy]

An import used only in javadoc is flagged as unused.

For example the "SomeUtility" class is flagged as unused when only used in javadoc like this:
/*
* The {@link SomeUtility#someHelperMethod(String, some.package.SomeObject)} method does something.
/
public void someMethod() {
}

[Andreas Dangel]

This looks similar to bug [#1181].

Can you please double check, that you really use a javadoc/formal comment starting with two asterisks?

/**
 * The {@link SomeUtility#someHelperMethod(String, SomeObject)} method does something.
 */
public void someMethod() { }

PMD really only considers FormalComment. With the above example, I can't reproduce the problem.

[Patrick McEvoy]

This works correctly (no false postive) in PMD 5.1.1. We did not pick up 5.1.2, 5.1.3, or 5.2.0. We are getting the problem on 5.2.1.

Here is a copy/paste of the code with renaming

import com.example.aaa.bbb.ccc.ddd.SomeUtility;
...
/**
* The {@link SomeUtility#getSomeDescriptor(String, com.example.aaa.bbb.xxx.SomeContext)}
* API sets a SomeRenderer onto the descriptor.

The SomeUtility and SomeContext classes are in different packages but in the same jar and the jar is in the auxclasspath.

I have not been able to reproduce this with a simple example.

[Patrick McEvoy]

The second argument is the key. If I change the source to import the class and then use just the short classname (i.e. SomeContext), then there is no false positive.

That is, this code gives a false postive
package com.example.factory;

import com.example.util.SomeUtility;

import org.junit.Test;

/
* SomeTest.
*/
public class SomeTest {
/
* The {@link SomeUtility#getSomeDescriptor(String, com.example.descriptor.SomeContext)}
* API sets a SomeRenderer onto the descriptor.
*/
@Test
public void testSomething() {
}
}

And this code does not produce a false positive
package com.example.factory;

import com.example.descriptor.SomeContext;
import com.example.util.SomeUtility;

import org.junit.Test;

/
* SomeTest.
*/
public class SomeTest {
/
* The {@link SomeUtility#getSomeDescriptor(String, SomeContext)}
* API sets a SomeRenderer onto the descriptor.
*/
@Test
public void testSomething() {
}
}

[Andreas Dangel]

Thanks! Yes, the second argument was the issue.
Will be fixed with the next pmd version. Thanks again!

[Robert Kang]

I can still reproduce this issue on 5.2.3 (maven repo 3.4).

[Andreas Dangel]

Thanks for the feedback!

Could you please post the javadoc snippet that still reproduces this false positive?

Thanks!

[Alexey Yudichev]

Still there in 5.3.5:

line 6: Avoid unused imports such as 'a.b.c.d.AgentState'

import a.b.c.d.AgentState; // line 6

//...

    /**
     * Gets all active AgentHandles.
     * <p/>
     * An agent is active if it has not posted a {@link AgentStateChangeEvent} containing {@link AgentState#TERMINATED}.
     *
     * @return agent handles.
     */
    Iterable<AgentHandle> getAgentHandles();

[Andreas Dangel]

Thanks for the example. Yes, indeed - this case is not covered (linking a field).
You can workaround this by adding an additional @see AgentState#TERMINATED.

I'll handle this additional issue in [#1465].