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

Close

#74 Import req'd by javadoc reported unused

release_4.1
closed
Oliver Burn
None
4
2014-08-27
2002-12-11
Patrick Tullmann
No

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
statement.

See:
http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/javadoc.html#howaclassmustbereferenced

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)
{
}
}

Discussion

  • Lars Kühne
    Lars Kühne
    2002-12-17

    Logged In: YES
    user_id=401384

    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
    2003-01-08

    Logged In: YES
    user_id=401384

    bug 654335 has been marked as a duplicate of this bug

     
  • Chuck Daniels
    Chuck Daniels
    2003-11-04

    Logged In: YES
    user_id=901295

    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
    2005-01-05

    Logged In: YES
    user_id=66520

    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
    2005-11-03

    Logged In: YES
    user_id=893980

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

     
  • Oliver Burn
    Oliver Burn
    2005-11-03

    Logged In: YES
    user_id=218824

    As a workaround instead of:

    • {@link ArrayList}.

    have:

    • {@link java.util.ArrayList}.
     
  • Stefan Hansel
    Stefan Hansel
    2006-07-17

    Logged In: YES
    user_id=609001

    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
    user_id=95933

    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
    2006-09-18

    Logged In: YES
    user_id=163572

    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 &
    @linkplain.

     
  • 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,
    Sébastien

     
  • I am just a user of checkstyle. You may stone me, but I think checkstyle is right.
    The problem is your IDE:
    https://bugs.eclipse.org/bugs/show_bug.cgi?id=128661

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

     
  • Johan Walles
    Johan Walles
    2010-03-24

    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
    Eric
    2011-01-19

    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
    2011-03-30

    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
    2011-07-11

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

     
  • Oliver Burn
    Oliver Burn
    2011-07-12

    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}
     */