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

incorrect use of `@author`

XMLWordPrintable

    • Icon: Bug Bug
    • Resolution: Won't Fix
    • Icon: P4 P4
    • None
    • None
    • core-libs
    • None

      Since forever, `@author` has only been permitted on comments on top-level declarations, and not on individual members of classes and fields.

      The following bad instances have been detected in JDK files:

      open/src/java.base/share/classes/java/math/BigDecimal.java:1736: warning: Tag @author cannot be used in method documentation. It can only be used in the following types of documentation: overview, module, package, class/interface.
           * @author Joseph D. Darcy
      open/src/java.base/share/classes/java/math/BigDecimal.java:1905: warning: Tag @author cannot be used in method documentation. It can only be used in the following types of documentation: overview, module, package, class/interface.
           * @author Joseph D. Darcy
      open/src/java.desktop/share/classes/java/awt/Component.java:9155: warning: Tag @author cannot be used in method documentation. It can only be used in the following types of documentation: overview, module, package, class/interface.
           * @author Laura Werner, IBM
      open/src/java.desktop/share/classes/java/awt/Component.java:9179: warning: Tag @author cannot be used in method documentation. It can only be used in the following types of documentation: overview, module, package, class/interface.
           * @author Laura Werner, IBM
      open/src/java.base/share/classes/java/lang/Double.java:403: warning: Tag @author cannot be used in method documentation. It can only be used in the following types of documentation: overview, module, package, class/interface.
           * @author Joseph D. Darcy
      open/src/java.base/share/classes/java/lang/Float.java:317: warning: Tag @author cannot be used in method documentation. It can only be used in the following types of documentation: overview, module, package, class/interface.
           * @author Joseph D. Darcy
      open/src/java.base/share/classes/java/lang/Math.java:2366: warning: Tag @author cannot be used in method documentation. It can only be used in the following types of documentation: overview, module, package, class/interface.
           * @author Joseph D. Darcy
      open/src/java.base/share/classes/java/lang/Math.java:2413: warning: Tag @author cannot be used in method documentation. It can only be used in the following types of documentation: overview, module, package, class/interface.
           * @author Joseph D. Darcy
      open/src/java.base/share/classes/java/lang/Math.java:2454: warning: Tag @author cannot be used in method documentation. It can only be used in the following types of documentation: overview, module, package, class/interface.
           * @author Joseph D. Darcy
      open/src/java.base/share/classes/java/lang/Math.java:2476: warning: Tag @author cannot be used in method documentation. It can only be used in the following types of documentation: overview, module, package, class/interface.
           * @author Joseph D. Darcy
      open/src/java.base/share/classes/java/lang/StrictMath.java:456: warning: Tag @author cannot be used in method documentation. It can only be used in the following types of documentation: overview, module, package, class/interface.
           * @author Joseph D. Darcy
      open/src/java.base/share/classes/java/lang/StrictMath.java:1886: warning: Tag @author cannot be used in method documentation. It can only be used in the following types of documentation: overview, module, package, class/interface.
           * @author Joseph D. Darcy
      open/src/java.base/share/classes/java/lang/StrictMath.java:1913: warning: Tag @author cannot be used in method documentation. It can only be used in the following types of documentation: overview, module, package, class/interface.
           * @author Joseph D. Darcy
      open/src/java.base/share/classes/java/lang/StrictMath.java:1934: warning: Tag @author cannot be used in method documentation. It can only be used in the following types of documentation: overview, module, package, class/interface.
           * @author Joseph D. Darcy
      open/src/java.base/share/classes/java/lang/StrictMath.java:1955: warning: Tag @author cannot be used in method documentation. It can only be used in the following types of documentation: overview, module, package, class/interface.
           * @author Joseph D. Darcy


      Whilst it would be possible to relax the rules, given there is a trend away from using `@author` tags in favor of relying on SCM metadata, it seems better to remove these tags.

      These warnings are showing up in enhanced checking in javadoc and `make docs`.

            jjg Jonathan Gibbons
            jjg Jonathan Gibbons
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Created:
              Updated:
              Resolved: