primer for writing Java 9 taglets

[Rick Hillegas]

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