primer for writing Java 9 taglets

[Rick Hillegas]

Hi Jon,

Dalibor Topic suggested that I share my experience adjusting Apache 
Derby's Taglet implementations and javadoc in order to compile cleanly 
without warnings using build 124 of JDK 9. My experience is documented 
in the 2016-07-16 - 2016-07-17 comments attached to 
https://issues.apache.org/jira/browse/DERBY-6856

Thanks again for your help,
-Rick

On 7/16/16, 8:30 AM, Rick Hillegas wrote:
> On 7/12/16 7:22 PM, Jonathan Gibbons wrote:
>>
>>
>> On 07/12/2016 06:45 PM, Rick Hillegas wrote:
>>> Hi Jon,
>>>
>>> Thanks for replying. Some comments inline...
>>>
>>> On 7/11/16 7:00 PM, Jonathan Gibbons wrote:
>>>>
>>>>
>>>> On 07/11/2016 06:28 PM, Rick Hillegas wrote:
>>>>> Hey folks,
>>>>>
>>>>> Is there a primer for writing Java 9 Taglets which is similar to 
>>>>> the primer for writing old-style Taglets found here: 
>>>>> http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/taglet/overview.html. 
>>>>> I am trying to get a clean, warning-free build of Apache Derby 
>>>>> using b124 of JDK 9. In order to do this, I need to eliminate the 
>>>>> doclet deprecation warnings introduced by b124.
>>>>>
>>>>> Thanks,
>>>>> -Rick
>>>>
>>>> Hi Rick,
>>>>
>>>> Yes, the world in this area has changed a lot in JDK 9.
>>>>
>>>> I'm assuming from your reference that your taglets do conform to 
>>>> the (simple) API in this page:
>>>> http://docs.oracle.com/javase/7/docs/jdk/api/javadoc/taglet/com/sun/tools/doclets/Taglet.html 
>>>>
>>>>
>>>> I say that to make sure you're not using the more complex internal 
>>>> API that never became officially public, and which accesses a lot 
>>>> of JDK-internal API.
>>>>
>>>> The good news for you is that there is a replacement; the bad news 
>>>> is the guides have not been updated, and worse, we don't currently 
>>>> publish any JDK 9 API docs other than the Java SE API. (But that's 
>>>> a separate issue we're working on.)   But the API is there, if 
>>>> you're prepared to build the docs. So, if you're able to build JDK 
>>>> 9, execute "make docs" to build the API docs. Then, in the 
>>>> build/$CONFIGURATION/images/docs directory, look for the API rooted 
>>>> at jdk/api/javadoc/doclet/index.html, i.,e.
>>>> build/$CONFIGURATION/images/docs/jdk/api/javadoc/doclet/index.html
>>>>
>>>> That will show you the new replacement API, using the DocTree API 
>>>> added as part of the Compiler Tree API , in JDK 8.
>>>> See here 
>>>> https://docs.oracle.com/javase/8/docs/jdk/api/javac/tree/index.html
>>>> and here: 
>>>> https://docs.oracle.com/javase/8/docs/jdk/api/javac/tree/com/sun/source/doctree/package-summary.html
>>>>
>>>> It should be reasonably simple to convert taglets from the old API 
>>>> to the new API.
>>> This is the crux of the problem. No doubt it looks simple to 
>>> experts. But it's puzzling me. I have indeed looked at the old and 
>>> new APIs.  Tags knew how to turn themselves into strings. Now Tags 
>>> have been replaced by DocTrees, which are phrased in terms of a 
>>> visitor pattern. Code for a sample Taglet.toString() implementation 
>>> would be helpful if you have it handy.
>>
>> The comment about looking simple to experts, but puzzling, is a 
>> reasonable one.
>>
>> If you have a jdk9/dev/langtools repo available, you can look at one 
>> of the simple test taglets:
>> langtools/test/jdk/javadoc/tool/api/basic/taglets/UnderlineTaglet.java
>>
>> That shows a visitor being used to render a tag to underline its 
>> content.  It uses SimpleDocTreeVisitor to save you implementing all 
>> the methods of the Visitor interface. You can implement as many of 
>> those methods as are likely to occur in your taglet.   As a general 
>> rule, any DocTree can be "converted" back to its original form with 
>> .toString(),  There are subtypes of DocTree for plain text, entities 
>> (e.g.  ), the start of an HTML element (e.g. <a href="url">) or 
>> the end of an HTML element. (e.g. </a>) The DocTree API makes no 
>> other attempt to parse HTML and to relate the start and end of 
>> elements, etc.
>>
>> I apologize ahead of time that the example is not a great one.  I see 
>> typos and obsolete references in the code (e.g.  "param tag he 
>> <code>Tag</code>") . It declares itself to be an inline tag, so you 
>> shouldn't need to provide visitUnknownBlockTag (because block tags 
>> cannot appear inside inline tags) and it would be better if 
>> visitUnknownInlineTag composed its contents in a StringBuilder, 
>> rather than just returning the first one.  A typical inline tag is 
>> likely to have content which is a sequence of DocTree nodes which may 
>> be text, entities and HTML.
>>
>>
>> Let me know if you need a somewhat more exemplary example.
> Thanks, Jon. That's what I needed. Applying that pattern across our 
> Taglets was a quick, mechanical task, as you predicted.
>
> Thanks,
> -Rick
>>
>>
>>
>>>
>>>>
>>>>
>>>> Given that the old Taglet API was a supported API in JDK 8, albeit 
>>>> a somewhat obscure one, it will continue to be available in JDK 9, 
>>>> although as you have seen, it is now deprecated. You can continue 
>>>> to use it, in conjunction with the old standard doclet, and simply 
>>>> suppress the deprecation warnings with 
>>>> @SuppressWarnings("deprecation").
>>> This is the last resort. So far I have managed to cope with all the 
>>> other deprecation warnings introduced by Java 9. I have not had to 
>>> suppress any warnings, but have, instead, managed to modernize the 
>>> Derby codebase. I'm hoping that a little sample code will help me 
>>> over this doclet speedbump.
>>
>> I applaud your zeal ;-)
>>
>>>
>>> Thanks,
>>> -Rick
>>>>   However, if you are looking to use a taglet in the new standard 
>>>> doclet (which understands JDK 9 modules) then you will have to 
>>>> convert to the new improved API.
>>>>
>>>> -- Jon
>>>>
>>>>
>>>>
>>>>
>>>>
>>>
>>
>>
>