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

Annotations in front of Javadoc comment prevent comment from being recognized

    XMLWordPrintable

Details

    • b02
    • generic
    • generic

    Description

      A DESCRIPTION OF THE PROBLEM :
      When annotations on an element are placed before the Javadoc comment, the comment is not properly recognized as documenting the element.

      This might be caught by `-Xdoclint:missing`, but often doclint is disabled or developers do not pay close attention to the warnings it produces.
      And this potential bug pattern of placing annotations in front of the Javadoc comment is quite common.
      Even the JDK source code contains occurrences of this for internal methods, e.g.:
      https://github.com/openjdk/jdk/blob/d191e475168f203bb448c4977f8d6d77b8658d25/src/java.base/share/classes/java/util/regex/Pattern.java#L2127-L2131

      Not sure if any of the specifications define where Javadoc comments may be placed, and whether that specification needs to be updated in case the current javadoc behavior is adjusted.

      STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
      Run `javadoc -Xdoclint:all Test.java` with the below source code as `Test.java`

      EXPECTED VERSUS ACTUAL BEHAVIOR :
      EXPECTED -
      The class documentation should be visible in the generated output
      ACTUAL -
      The javadoc tool emits the following warning and the class documentation is missing:
      >Test.java:5: warning: no comment
      > public interface Test {}

      ---------- BEGIN SOURCE ----------
      @Deprecated
      /**
       * Class doc
       */
      public interface Test {}

      ---------- END SOURCE ----------

      Attachments

        Issue Links

          Activity

            People

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

              Dates

                Created:
                Updated:
                Resolved: