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

Store and pass in translated doc comments for values() and valueOf() of Enum

XMLWordPrintable

    • Icon: Enhancement Enhancement
    • Resolution: Fixed
    • Icon: P4 P4
    • 9
    • 5.0
    • tools

      Devise a mechanism to store translated doc comments
      for generated static methods, one that can store those comments
      outside of the Javadoc tool. In particular, this applies
      to the values() and valueOf() generated methods of an Enum class.

      Background:
      The values() and valueOf() methods of an Enum class are generated
      by the compiler, much like default constructors. However, unlike
      default constructors, the compiler prohibits them from being
      overridden in the source file. Therefore, the doc comments
      cannot be stored in the source file.

      The default doc comments for these methods are now stored in the
      resource file doclets.properties, according to this bug report:
      5004549: No spec for values() and valueOf() method of a Enum class
      The resource file belongs to the doclet toolkit API:
      src/share/classes/com/sun/tools/doclets/internal/toolkit/resources/doclets.properties
      There is a need for the doc comments to reside elsewhere, so they
      can be easily translated into other languages without having
      to translate that part of the doclet toolkit. FWIW, Sun
      translates the Javadoc tool (including doclets.properties)
      into only one other language -- Japanese.

      Requirements:
      It must be possible for a given version of Javadoc to generate
      full documentation from doc comments of any language
      residing in either of two places:
       - java source files (using the standard doclet)
       - .cmnt files (using the localization doclet)

      - When implementing multiple Enums, it seems sufficient to have
        one doc comment for all values() methods.

      As an example, it must be possible for a javadoc tool written in
      Spanish to generate full French documentation from source files
      that contain French doc comments. It must also be possible to
      import full German doc comments from .cmnt files to generate
      full German documentation.

            bpatel Bhavesh Patel (Inactive)
            dkramersunw Douglas Kramer (Inactive)
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Created:
              Updated:
              Resolved:
              Imported:
              Indexed: