-
Enhancement
-
Resolution: Fixed
-
P4
-
5.0
-
generic
-
other
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.
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.
- relates to
-
JDK-8020663 Restructure some properties to facilitate better translation
-
- Closed
-