Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8265253

javac -Xdoclint:all gives "no comment" warning for code that can't be commented

    XMLWordPrintable

    Details

    • Subcomponent:
    • Resolved In Build:
      b12
    • CPU:
      x86_64
    • OS:
      windows_10

      Description

      ADDITIONAL SYSTEM INFORMATION :
      Windows 10
      Java 16

      A DESCRIPTION OF THE PROBLEM :
      Useful thread - https://stackoverflow.com/questions/67010921/

      If I attempt to use "javac -Xdoclint:all" on code that contains an optional anonymous class, javac will return a warning, telling me that I am missing a comment for that anonymous optional class. The problem is, there is no possible way to document an optional anonymous class in a way that satisfies javac. It will flag it no matter what.

      STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
      1 - On a system with a current Java setup, copy the attached program into a directory.

      2 - Compile the program on the commandline with the following command

      javac -Xdoclint:all Xdoclint.java

      EXPECTED VERSUS ACTUAL BEHAVIOR :
      EXPECTED -
      The code should compile with no warnings.
      ACTUAL -
      It compiles with the following error

      Xdoclint.java:10: warning: no comment
         A
         ^
      1 warning

      ---------- BEGIN SOURCE ----------
      /** Comment. */
      public
      /** Comment. */
      enum
      /** Comment. */
      Xdoclint
      /** Comment. */
      {
      /** Comment. */
         A
         /** Comment. */
         {
         /** Comment. */
         }
      /** Comment. */
         ,
      /** Comment. */
         ;
      /** Comment. */
      }
      /** Comment. */
      ---------- END SOURCE ----------

      CUSTOMER SUBMITTED WORKAROUND :
      Technically speaking, you can use the following command to bypass this

      javac -Xdoclint:all,-missing/private Xdoclint.java

      However, this workaround has a few problems.

      First off and most importantly, it doesn't solve the problem, it just avoids it.

      Second off, it actually hides warnings that should be thrown from a private instance field that is missing a comment. Take the test case code, make a new line after the only semicolon in the test case, then paste the following code into the newly created line "private int a = 0;" Now, compile it with the "workaround", and you will see that it does not report a warning when it should. The line directly above it is a semicolon, not a comment, and therefore, violates javadoc. Therefore, it should throw a warning, but it does not. However, if you redo the same sequence of steps, but use a public int instead of a private one, you will see that it returns the expected error.

      Third off, it also hides missing comments for everything contained within the optional anonymous class. Make a new line after the opening curly brace of the optional anonymous class, then paste the following code into the newly created line "public int b = 0;". Then compile it with the workaround and you will see that it does not return a warning when it should.

      Point is, this workaround can cause lots of problems, so I hesitate to call it a workaround, but it seems like the best option available.

      FREQUENCY : always


        Attachments

          Issue Links

            Activity

              People

              Assignee:
              jjg Jonathan Gibbons
              Reporter:
              webbuggrp Webbug Group
              Votes:
              0 Vote for this issue
              Watchers:
              5 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: