primer for writing Java 9 taglets

[Jonathan Gibbons]

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.


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