|
Description
|
This proposal is an update to 4421066. It modifies an interface
change that has not yet been publically released.
Background
The javadoc tool maintains backward compatibility for "legacy" doclets --
those not aware of the Tiger language features. It modifies the
results of a number of methods to match as closely as possible the
pre-Tiger results. For example, type parameters are elided.
The javadoc tool must be able to determine if a doclet supports the
1.5 language features. It currently relies on a marker interface
Doclet15 for new doclets to implement. The name Doclet15, and
its use as a marker interface, are ugly and nonintuitive. It would be
ideal if we could have a Doclet interface for doclets to implement.
Unfortunately the class name Doclet is already taken by a so-called
"example" doclet, and the entry point methods of a doclet are all (for
no customer reason) static.
Proposal
Drop Doclet15. Instead, a doclet should indicate its language version
by supplying a languageVersion method. This has the side benefit of
being extensible for possible language changes in, say, Mustang. The
"example" Doclet class has the following addition:
/**
* Return the version of the Java Programming Language supported
* by this doclet.
* <p>
* This method is required by any doclet supporting a language version
* other than 1.1.
*
* @return the language version supported by this doclet;
* default is 1.1
* @since 1.5
*/
public static LanguageVersion languageVersion() {
return LanguageVersion.JDK1_1;
}
LanguageVersion is defined as:
/**
* Java Programming Language version. The constants of this enum
* identify the JDK and J2SE releases containing language changes
* relevant to doclets.
* <p>
* All doclets support at least the 1.1 language version.
* The first release subsequent to this with language changes
* affecting doclets is 1.5.
*
* @since 1.5
*/
public enum LanguageVersion {
/** JDK 1.1: added nested classes and interfaces. */
JDK1_1,
/** J2SE 1.5: added generic types, enums, varargs, and annotations. */
J2SE1_5
}
|
