Public API for programmatic registration of Taglet?

[Jonathan Gibbons]

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- 
>>>
>>>
>>>
>>>
>