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

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

    XMLWordPrintable

Details

    Backports

      Description

         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.

        Attachments

          Issue Links

            Activity

              People

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

                Dates

                  Created:
                  Updated:
                  Resolved: