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

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

                  Dates

                  Created:
                  Updated:
                  Resolved: