primer for writing Java 9 taglets

[Rick Hillegas]

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.

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

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