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

☂ Missing documentation in JavaFX API

    XMLWordPrintable

    Details

    • Type: Task
    • Status: Open
    • Priority: P4
    • Resolution: Unresolved
    • Affects Version/s: None
    • Fix Version/s: openjfx18
    • Component/s: javafx
    • Labels:

      Description

      This is an umbrella task to track improving the JavaFX API docs, specifically relating to API elements where the documentation is missing. Bugs or RFEs to address these issues will be tracked with linked blocking issues. Many of these problems are related to JavaFX properties, but there are other constructors, methods, and fields that are missing documentation as well.

      The javadoc tool in JDK 16 and later produces warnings if a constructor, method, or field that is part of the API has no javadoc comments. Currently the tool produces several spurious warnings, but the fix for JDK-8269774 (which is under review), will eliminate those such that what remains are valid problems in the FX API documentation.

      Before listing the specific problems that I have found, here is some background information on JavaFX properties. Most of the Definitions section came from a writeup that Jon attached to JDK-8270195 as "fx-notes.md", which has many additional details if more information is desired.


      Definitions:

      * A property is defined implicitly by a no-args method whose name ends in Property and whose return type is a subtype of javafx.beans.Observable.

      * The name of the property is the part of the method name before "Property". The type of the property is the return type of the method. The name of the property must not start with "get", "set", or "is" and must not end with "Property". It should be camel case with an initial lower-case letter so that all methods follow the usual convention.

      * A property may have a like-named field of the appropriate type. The field is typically private.

      * A property may have getter and setter methods. The getter method may be named "is..." for boolean properties, and typically is so named.


      Examples:

      * A double property named "layoutX"

      private DoubleProperty layoutX;
      public final DoubleProperty layoutXProperty() { ... }
      public final double getLayoutX() { ... }
      public final setLayoutX(double val) { ... }

      * A read-only boolean property named "disabled" (so no setter)

      private ReadOnlyBooleanProperty disabled;
      public final ReadOnlyBooleanProperty disabledProperty() { ... }
      public final double isEnabled() { ... }


      Rules and best practices:

      1. As a rule, exactly one of the (private) xxxxx field or the xxxxxProperty() method must have a javadoc comment block for a given property. This is used as the description for that property. If the description is on the Property method it should include an `@return` tag. It is a mistake to add javadoc comments to both the field and the Property method. This will lead to a non-suppressable warning in a future version of the javadoc tool. If neither the method nor field has a javadoc comment block, the javadoc tool will issue a warning that the method has no comments. The generated API docs will not have any description for that property. Note that a Property method in a subclass need not have documentation if that method overrides a Property method defined in a (usually abstract) superclass or interface that has the documentation.

      2. As a best practice, the setter and getter methods, if present, should not have any API docs. Anything relating to the use or description of the property should go into the description on the field or Property method. An exception to this can be made if are special considerations for the method itself (e.g., if the setter or getter needs a different `@since` tag because it was added after the Property method). There should only be a very few examples where this is needed.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              kcr Kevin Rushforth
              Reporter:
              kcr Kevin Rushforth
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

                Dates

                Created:
                Updated: