On 4/18/18 9:08 AM, Martin Desruisseaux wrote:
Hello
I'm trying to write an extension of the standard doclet together with
custom taglets in the same JAR file. The custom taglets and doclet
need to share information. But I faced the following difficulties:
When the Taglet.init(DocletEnvironment,Doclet) method is invoked, the
doclet argument given by the caller is the internal HtmlDoclet wrapped
by StandardDoclet, not my custom StandardDoclet subtype. So I can not
get my doclet and taglet in touch that way.
The lazy workaround - shared static fields - does not work because the
taglet is loaded in a different class loader than the doclet. So even
if I change a static field value from the taglet, the doclet never see
that change. This is not a multi-threading issue; I tested with
volatile static field. I also verified that the class loaders for the
same class were different depending on whether the class of my JAR
file is accessed from the doclet or from the taglet.
I tried to wrap DocletEnvironment in order to return a customised
ForwardingJavaFileManager, in an attempt to control which ClassLoader
is used for loading the taglet. But the standard doclet does not seem
to accept customized DocletEnvironment, as suggested by the error that
I got:
java.lang.ClassCastException:
org.opengis.tools.doclet.ForwardingDocletEnvironment cannot be cast to
jdk.javadoc/jdk.javadoc.internal.tool.DocEnvImpl
at
jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.WorkArounds.<init>(WorkArounds.java:101)
at
jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.AbstractDoclet.run(AbstractDoclet.java:108)
at
jdk.javadoc/jdk.javadoc.doclet.StandardDoclet.run(StandardDoclet.java:72)
(...snip...)
The jdk.javadoc.internal.doclets.toolkit.taglets.TagletManager class
has public void addCustomTag(Taglet) method which seems perfect for my
need, but I found no public API for accessing this functionality.
Is there a public way for a doclet to know its registered taglets, or
any other workaround that I may have missed? If not, would the
following evolution of Javadoc tools be possible?
* When extending the StandardDoclet, the doclet given in
Taglet.init(...) method should be the user StandardDoclet instance
instead than the JDK internal HtmlDoclet.
* Alternatively, a public API for addCustomTag(…) functionality
would also work.
Regards,
Martin
Martin,
You are (regrettably) on the bleeding edge here with this use of the
recent new Doclet API.
I would somewhat rephrase your first bullet, to reflect the intent of
the API
* Whatever the doclet, the doclet given in Taglet.init(...) method
should be the user doclet, whether specified explicitly or by default
Given that redefinition, the behavior you describe can reasonably be
described as a bug. This would require a minor spec change of the
doclet parameter: "doclet - the doclet that instantiated this taglet"
It is true that there is no public API (except for option support) on
StandardDoclet to access some of the features of the standard doclet.
And, I don't think we should go all the way with methods to access all
the individual features. But, there is precedent in other similar APIs
for adding methods to provide instances of objects that might otherwise
be created in problematic classloaders. The most notable case is the
ability to provide instances of annotation processors to javac [1]
The problem in this case would be the specification of such a method.
While it would be easy to write "Adds a custom tag." the order of the
calls has a visible impact on the generated documentation that would be
harder to specify and/or provide full control.
-- Jon
[1]
https://docs.oracle.com/javase/9/docs/api/javax/tools/JavaCompiler.CompilationTask.html#setProcessors-java.lang.Iterable-
