CODEWITHSUNDEEP
javajavadocjava-annotations
peer
peer

Reputation: 4729

What does `@SuppressWarnings("javadoc")` do? When is it Redundant?

I have @SuppressWarnings("javadoc") on almost every class. My IDE gives me a warning on virtually all of them: "Redundant suppression". I assume advances in technology have made this annotation obsolete, but would like to understand what this annotation did in the first place. I could not find anything helpful. Apparently it suppresses compiles warnings, but I couldn't find anything on the argument "javadoc". And my code does compile, why would javadoc stand in the way of compiling anyway?

Upvotes: -4

Views: 110

Answers (2)

Marcono1234
Marcono1234

Reputation: 6934

@SuppressWarnings("javadoc") seems to be a non-standard warning suppression introduced by IDEs, first by Eclipse and later by IntelliJ IDEA.

IntelliJ IDEA

At least IntelliJ still seems to recognize it, but you have to make sure the @SuppressWarnings annotation occurs after the Javadoc comment (otherwise the comment is not recognized as Javadoc, related JDK-8294007).

For example here it suppresses the (correct) warning about the @return for a void method:

/**
 * @return some value
 */
@SuppressWarnings("javadoc")
void doSomething() {
}

However, it only seems to work for some Javadoc warnings / errors. For example for {@link ...} referring to a non-existent type it does not work. You have to use @SuppressWarnings("JavadocReference") there instead, you will see this when using the "Suppress for ..." action on the error.

JDK javadoc tool

The JDK javadoc tool does not seem to recognize @SuppressWarnings("javadoc").

However, starting with JDK 18 it supports @SuppressWarnings("doclint"), see JDK-8274926, for example to suppress warnings about missing Javadoc comments.
But it does not seem to suppress errors, such as when using @return on a void method.

Upvotes: 1

peer
peer

Reputation: 4729

@SuppressWarnings("javadoc") suppresses warnings about wrong javadoc, e.g. missing @param descriptions. An IDE will highlight such errors. This highlighting can be suppressed with @SuppressWarnings("javadoc"). The annotation is redundant when there are no such errors in the javadoc of a class. If the annotation is not redundant and removed new warnings will show up detailing the javadoc errors.

Upvotes: 0

Related Questions