Right now we process the javadoc of ICU4J with several doclets / taglets.
These are extensions to the standard JDK javadoc tool, and we use them in several places:
Render the custom ICU tags in the generated javadoc html. Things like @icu, @draft, @internal, @stable, @discouraged, and so on
Using the JCite tool (third party, abandoned) we inject syntax highlighted code samples in the javadoc. The samples come from real Java files, so we know they compile. And example here:
We also use custom doclets to collect data for the API reports, and to validate the status annotations are present and consistent (draft / stable / internal etc).
All of these extensions are built on top of APIs provided by com.sun.javadoc .
That was completely removed in JDK 9.
So now to do any of the tasks above (generate Javadoc, API reports, tag / annotation checking), one must download and use a “real” JDK 8. There is no way to use a more modern JDK (like 11 or 17 or above).
And it is also problematic when opening the ICU4J Maven project in IDEs, since most of them moved away from JDK 8. There are ways to download and configure the IDEs with JDK 8, but that adds friction to anyone wanting to work on ICU4J.
TLDR: migrate all custom doclets / taglets from com.sun.javadoc (removed in JDK 9) to jdk.javadoc.doclet.
Right now we process the javadoc of ICU4J with several doclets / taglets.
These are extensions to the standard JDK
javadoctool, and we use them in several places:Render the custom ICU tags in the generated javadoc html.
Things like
@icu,@draft,@internal,@stable,@discouraged, and so onUsing the JCite tool (third party, abandoned) we inject syntax highlighted code samples in the javadoc.
The samples come from real Java files, so we know they compile.
And example here:
We also use custom doclets to collect data for the API reports, and to validate the status annotations are present and consistent (draft / stable / internal etc).
All of these extensions are built on top of APIs provided by
com.sun.javadoc.That was completely removed in JDK 9.
So now to do any of the tasks above (generate Javadoc, API reports, tag / annotation checking), one must download and use a “real” JDK 8. There is no way to use a more modern JDK (like 11 or 17 or above).
And it is also problematic when opening the ICU4J Maven project in IDEs, since most of them moved away from JDK 8. There are ways to download and configure the IDEs with JDK 8, but that adds friction to anyone wanting to work on ICU4J.