Public API for programmatic registration of Taglet?

[Jonathan Gibbons]

Tracked as JDK-8201817
https://bugs.openjdk.java.net/browse/JDK-8201817

-- Jon


On 4/18/18 11:39 AM, Jonathan Gibbons wrote:
> 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- 
>>>>
>>>>
>>>>
>>>>
>>
>