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