primer for writing Java 9 taglets

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

primer for writing Java 9 taglets

Rick Hillegas
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
Reply | Threaded
Open this post in threaded view
|

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




Reply | Threaded
Open this post in threaded view
|

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

Reply | Threaded
Open this post in threaded view
|

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

Reply | Threaded
Open this post in threaded view
|

Re: primer for writing Java 9 taglets

Rick Hillegas
On 7/12/16 7:22 PM, Jonathan Gibbons wrote:

>
>
> 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. &nbsp;), 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.
Thanks, Jon. That's what I needed. Applying that pattern across our
Taglets was a quick, mechanical task, as you predicted.

Thanks,
-Rick

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

Reply | Threaded
Open this post in threaded view
|

Re: primer for writing Java 9 taglets

Rick Hillegas
Hi Jon,

Dalibor Topic suggested that I share my experience adjusting Apache
Derby's Taglet implementations and javadoc in order to compile cleanly
without warnings using build 124 of JDK 9. My experience is documented
in the 2016-07-16 - 2016-07-17 comments attached to
https://issues.apache.org/jira/browse/DERBY-6856

Thanks again for your help,
-Rick

On 7/16/16, 8:30 AM, Rick Hillegas wrote:

> On 7/12/16 7:22 PM, Jonathan Gibbons wrote:
>>
>>
>> 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. &nbsp;), 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.
> Thanks, Jon. That's what I needed. Applying that pattern across our
> Taglets was a quick, mechanical task, as you predicted.
>
> Thanks,
> -Rick
>>
>>
>>
>>>
>>>>
>>>>
>>>> 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
>>>>
>>>>
>>>>
>>>>
>>>>
>>>
>>
>>
>