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
