javadoc -Xdoclint keeps flagging my (optional) anonymous class for not having a comment when it clearly does

I am using javadoc to document my public enum. I am compiling all of my following examples using the following command:

javac   -Xdoclint:all     LetsLearnJavadocXdoclint.java

If my enum is like this, it generates a .class file without any warnings.

/** Comment LetsLearnJavadocXdoclint. */
public enum LetsLearnJavadocXdoclint
{
   /** Comment A. */A;
}

But if my enum is like this:

/** Comment LetsLearnJavadocXdoclint. */
public enum LetsLearnJavadocXdoclint
{
   /** Comment A. */A{};
}

…..I get the following error…..

LetsLearnJavadocXdoclint.java:4: warning: no comment
   /** Comment A. */A{};
                    ^
1 warning

Thinking I needed to put the comment somewhere else, I decided to put a comment into every possible position…..

/** Comment LetsLearnJavadocXdoclint. */
public enum LetsLearnJavadocXdoclint
{
   /** Comment A. */A/** Comment A. */{/** Comment A. */}/** Comment A. */;
}

…..to no avail…..

LetsLearnJavadocXdoclint.java:4: warning: no comment
   /** Comment A. */A/** Comment A. */{/** Comment A. */}/** Comment A. */;
                    ^
1 warning

And to be absolutely, positively certain, I went to the logical extreme.

/** At this. */
public
/** point, I. */
enum
/** am beginning. */
LetsLearnJavadocXdoclint
/** to think. */
{
/** that I. */
   A
   /** am not. */
   {
   /** the one. */
   }
/** who is. */
   ,
/** at fault. */
   ;
/** here. */
}
/** Next question. How do I report a bug to Java? */

…..and still got…..

$ javac -Xdoclint:all LetsLearnJavadocXdoclint.java
LetsLearnJavadocXdoclint.java:10: warning: no comment
   A
   ^
1 warning

Am I missing something?

And to explain my intent a little better, my actual goal is to have this enum implement an interface with a single method, and then have every enum value within my enum provide their own unique implementation of the method. I have been trying to document it using javadoc, but to no avail. And that is how I came up with this minimal example.

If I had to guess, it probably has something to do with anonymous classes. I think those curly braces I included are creating some form of anonymous class, and it is trying to comment both the anonymous class AND the enum value. I guessed this because of the following example.

If I attempt to do this…..

/** Comment LetsLearnJavadocXdoclint. */
public enum LetsLearnJavadocXdoclint
{
   A{};
}

…..I get this…..

LetsLearnJavadocXdoclint.java:4: warning: no comment
   A{};
   ^
LetsLearnJavadocXdoclint.java:4: warning: no comment
   A{};
   ^
2 warnings

2 warnings

…..which immediately makes me think anonymous classes.

Obviously, I don’t know for sure, but why else would it have 2 WARNINGS unless it was because there was the enum class, and the anonymous class that it was expecting documentation from?

Finally, here is my information.

$ javac -version
javac 1.8.0_281

$ java -version
java version "1.8.0_281"
Java(TM) SE Runtime Environment (build 1.8.0_281-b09)
Java HotSpot(TM) 64-Bit Server VM (build 25.281-b09, mixed mode)

Answer

The optional class body of an enum constant implicitly defines an anonymous class declaration (see the Java Language Specification). The Javadoc tool does not directly document anonymous classes — that is, their declarations and doc comments are ignored. The following example of an anonymous class produces the same two warnings:

public class MyClass {

  private Runnable cleanUpOperation = new Runnable() {

    @Override
    public void run() {

    }
  };

}

One warning for the missing comment of the cleanUpOperation field and one for the missing comment of the anonymous sub class of Runnable. There is no way to add a comment to an anonymous class. Oracle suggests to document an anonymous class in the doc comment of its outer class or any other closely related class (for details see here). So in your case this would be the doc comment of your enum class or the enum constant.

-Xdoclint:all shows a warning for missing javadoc comments for public, protected, package and private members. This includes also anonymous classes.

To get rid of your warnings you could tell doclint to ignore missing comments for private members with -Xdoclint:all,-missing/private. Execute javac -X for help on how to configure doclint for your purposes.