OK, we can't easily accept arbitrary subtypes of DocletEnvironment,
without embarking on a bunch of changes to other public API.
This means the correct solution here is that Taglet.init should be
called with the "user doclet" (which we expect people to provide
subtypes of) and the system-provided DocletEnvironment (which we do not
expect people to subtype.)
The spec change here (for the @param doclet) is not a material change;
it is a clarification of the original intent. We just need to think of
the best words to describe the usage without getting into the internal
details of StandardDoclet delegating to HtmlDoclet.
-- Jon
On 4/18/18 10:50 AM, Jonathan Gibbons wrote:
Yes, it is on my list to dig into the details of why the
ClassCastException is being thrown.
-- Jon
On 4/18/18 9:53 AM, Martin Desruisseaux wrote:
Hello Jonathan
Thanks for your reply. Indeed, I understand that adding new API can be
tricky. If it is desired to avoid that path, modifying the
Taglet.init(…) specification the way you rephrased would help a lot.
Alternatively, another way to work without any specification change may
be to allow StandardDoclet.run(...) to accept arbitrary
DocletEnvironment without throwing ClassCastException.
Regards,
Martin
Le 18/04/2018 à 18:37, Jonathan Gibbons a écrit :
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-
