primer for writing Java 9 taglets

[Jonathan Gibbons]

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