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

doclint reports missing javadoc comments for JavaFX properties if the docs are on the property method

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: Resolved
    • Priority: P3
    • Resolution: Fixed
    • Affects Version/s: 16
    • Fix Version/s: 18
    • Component/s: tools
    • Labels:
      None

      Description

      This is a follow-on to JDK-8249633. We noticed this recently when we switched to using JDK 16 as the boot JDK for building JavaFX 17.

      Running doclint on the JavaFX API classes reports missing javadoc comments for JavaFX properties where the docs are on the property method instead of the (private) property object.

      If the docs are either on the private xxxxx property object or on the xxxxxProperty() method, the correct javadocs will be generated. For example:

      case 1: docs on the property object (this is the more common case)

          /**
           * The foo property.
           */
          private DoubleProperty foo;

          public final DoubleProperty fooProperty();

          public final double getFoo();

          public final void setFoo(double foo);


      case 2: docs on the property method

          private DoubleProperty bar;

          /**
           * The bar property.
           * @return the property object
           */
          public final DoubleProperty barProperty();

          public final double getBar();

          public final void setBar(double bar);


      Both cases will generate the correct docs, but in the latter case, an incorrect "missing comments" warning is generated.

      I can create a test case, or you can reproduce this by cloning https://github.com/openjdk/jfx.git and building the docs as follows:

      $ bash gradlew --info javadoc

      If I increase the max warnings we get a total of 528 warnings. Some of the warnings are very likely valid, but most of the ones I spot checked are because of this bug.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              jjg Jonathan Gibbons
              Reporter:
              kcr Kevin Rushforth
              Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: