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

Block comments of form '/***' are treated as javadoc comments

XMLWordPrintable

         See JDK-8271083 for a general description.

        Several JavaFX classes have block comments of the following form:

        ```
            /***************************************************************************
             * ...
             **************************************************************************/
        ```

        This pattern is treated as a javadoc comment and should be avoided. It can cause problems if the element that follows is a field or method that doesn't otherwise have or need a comment. For example, Node.java has the following:

        ```
            /***************************************************************************
             * *
             * Component Orientation Properties *
             * *
             **************************************************************************/
            private ObjectProperty<NodeOrientation> nodeOrientation;
        ```

        which causes "Component Orientation Properties" to be used as the definition of that field. It is then copied to the getter and setter instead of the description of the Property method.

        https://openjfx.io/javadoc/16/javafx.graphics/javafx/scene/Node.html#getNodeOrientation()

        This specific example will also lead to warnings from a future version of the javadoc tool, since there is redundant documentation on the field and the Property method.

        We should avoid using a / followed by 3 or more asterisks in block comments.

              kcr Kevin Rushforth
              kcr Kevin Rushforth
              Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

                Created:
                Updated:
                Resolved: