Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo


#74 Import req'd by javadoc reported unused

Oliver Burn
Patrick Tullmann

Some import statements in a .java source file may not
be necessary for compilation, but are required for
javadoc to generate pretty hyperlinks. Basically, if a
class in a different package is referenced only in an
@see or @link in a comment, javadoc requires an import


Here's an example:

import java.util.List;
import java.util.ArrayList;

* Example of an import that is needed for
* javadoc, but not javac.
* Remove the 'import java.util.ArrayList'
* and javadoc will complain.
public class Importdoc

* Munge a List. Optimized for the case
* where l is an
* {@link ArrayList}.

* @param l the list to munge

public void mungeList(List l)


  • Lars Kühne
    Lars Kühne

    Logged In: YES

    Yes, I consider this a bug.

    A workaround is to use {@link java.util.ArrayList}, but the
    above code should really pass CheckStyle.

  • Lars Kühne
    Lars Kühne

    Logged In: YES

    bug 654335 has been marked as a duplicate of this bug

  • Chuck Daniels
    Chuck Daniels

    Logged In: YES

    If you remove the import for java.util.ArrayList and change
    your link to {@link java.util.ArrayList}, then neither
    Checkstyle nor javadoc will complain.

  • Ken Arnold
    Ken Arnold

    Logged In: YES

    Removing the import is a workaround, but for me it would not be a
    solution. Our style is that the javadoc uses the imported name, and so
    there are names that are only used in javadoc. This keeps the javadoc
    more compact and easier to read in the file. (You don't need to agree;
    this is what we feel.)

    This problem has caused me to turn off this check completely.

  • Etienne Studer
    Etienne Studer

    Logged In: YES

    We have the same issue and it would be great if this got
    fixed for 4.0!

  • Oliver Burn
    Oliver Burn

    Logged In: YES

    As a workaround instead of:

    • {@link ArrayList}.


    • {@link java.util.ArrayList}.
  • Stefan Hansel
    Stefan Hansel

    Logged In: YES

    We consider it as a bug too.

    The workaround doesn't help us, because there is no
    convenient way to change all unqualified names to a
    qualified name.

    Since we work with eclipse-autocompletion we always get the
    unqualified name in our javadocs (+the import).

    This is very annoying.

  • Logged In: YES

    We also use Eclipse and it's really annoying having to
    qualify all the javadoc referenced types. Would be great to
    have a property to avoid that.

  • Paul Guyot
    Paul Guyot

    Logged In: YES

    I'm annoyed by this one, too. I've just submitted a patch
    towards the fix of this bug (1560482). It only fixes it for
    @see tag for now, but it could easily be extended to @link &

  • Hello,

    Do you have any update on this? We are trying to put in place a Checkstyle check when building our code, and the UnusedImport check is out for now because of the mentioned bug.

    Best regards,

  • I am just a user of checkstyle. You may stone me, but I think checkstyle is right.
    The problem is your IDE:

    However for convenience checkstyle should add a trigger to allow to accept such situation.

  • Johan Walles
    Johan Walles

    How to treat imports required by javadocs only is a matter of taste, and it would be very nice if the current UnusedImports check could get an option for how to handle such imports.

    Right now we have this check turned off since we get too many false positives. Being able to configure it to accept javadoc as a reason for an import would enable us to turn it on again.

  • Eric

    I'll add a "me too" to this one.

    Without this option, checkstyle forces the user to to use the fully qualified class names in cases where your javadoc is referencing classes that your code is not. This is just plain ugly.

  • Stevo Slavic
    Stevo Slavic

    Following javadoc FAQ explains that referenced class "must be referenced by a declaration or any kind of import statement": http://java.sun.com/j2se/javadoc/faq/index.html#missinglinks

    IMO proper solution would be to fix "Unused imports" check so +1 for that. Current workaround is to reference class using full class path and not just by name.

  • Sergei Ivanov
    Sergei Ivanov

    Please implement a fix for this issue, it's been bugging us for years.

  • Oliver Burn
    Oliver Burn

    Fixed in changeset 10b232dfd037

  • Thank you, however, this doesn't cover nested classes. For example:

    import Foo;
     *  {@link Foo.Bar}

    would be reported, while shouldn't.

    Last edit: Dzmitry Lazerka 2014-06-10
  • Same thing about fields:

    import Foo;
     * {@link Foo#BAR}