From jonathan.gibbons at oracle.com  Wed Jul  6 00:20:32 2016
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Tue, 05 Jul 2016 17:20:32 -0700
Subject: RFR: 8159305: Enhance the javadoc tool to support module related
	options
In-Reply-To: <576879C5.3020306@oracle.com>
References: <576879C5.3020306@oracle.com>
Message-ID: <577C4ED0.20909@oracle.com>



On 06/20/2016 04:18 PM, Kumar Srinivasan wrote:
> Hello,
>
> Please review the changes to fix:
> https://bugs.openjdk.java.net/browse/JDK-8159305
>
> The webrev is here:
> http://cr.openjdk.java.net/~ksrini/8159305/webrev.00/
>
> The spec-diff is here for reference:
> http://cr.openjdk.java.net/~ksrini/8159305/spec-diff/overview-summary.html 
>
>
>
> Thanks
> Kumar
>

DocletEnvironment: general  changes will require a CCC.

DocletEnvironment:61

"annotations" is wrong.   You mean "annotation types".  An "annotation" 
is the *use* of an annotation type.

line 101, don't like the "style" of plural type names (like 
"ModuleElements") in plain text. Type names should be in {@code} font.  
Consider using the underlying English words. (module elements, package 
elements, etc). If in doubt, follow whatever style Joe uses in the 269 API.

linbe 142. terse

doclet/package-info:63 plural type names again
Should use code form for any occurrence of an option name

60/61 the name is "included" but the <em> term is "specified". Not good 
to be inconsistent.
89 uses both, I'm not usre if the two are the same or different.


AbstractExecutableMemberWriter, 118, who is "we"?  Could improve 
phrasing, but I accept it's internal API.


AnnotationTypeRequiredMemberImpl, 108, OK, itr's an overloaded method, 
but I simply note that in this override, the parameter is ignored.


ConfigurationImpl 422
replace    DocPath.empty.resolve with plain old "new DocPath"

AbstractDoclet 119
Uugh

Configuration 358
Bad grammar/punctuation.   I'm surprised by the ordering of the decls 
for modules and modulePackages. I would have thought that modules is the 
dominant declaration here, and the modulePackages is derived from 
modules;  instead, the comment makes it seem like it's the other way 
around.  And, according to the code in initModules, the description is 
wrong anyway.

Configuration 392, initModules, similar to preceding comment. I think 
you have the role of modules and modulePackages backwards. Create 
"modules" first, add in the specifiedModules, then add in the packages.

Configuration 420, why the guard, are you worried about calling this 
multiple times?

TypeElementCatalog 103, redundant TypeELementCatalog.this (looks like NB 
error)

Utils is a bit of a mess, taken in conjunction with Configuration. 
There's a no-reason split between stuff in Utils and stuff in Configuration.

DocEnv
funky imports order

DocEnv.ModulePackage  ... an interface? really?   why not just a class 
containing two public final strings?

JavadocTool ... IncludesTable looks big enough to be split into its own 
top level class, and *maybe* should start becoming the basis of a new 
abstraction for all "included" stuff on the command, i.e. superseding 
code from Configuration and Utils.

JavadocTool.IncludesTable.ModulePackage. Over-engineered.

RootDocImpl:
more lack of abstraction with regard to stuff specified on the command line.

ToolOption
add M as an alias for MODULE

New long form options (SHOW_MODULES, etc) use space or = as a separator, 
not :

ToolOption.AccessHelper looks misguided.  Either the functionality here 
should be merged into Helper, or it should possibly be renamed and 
become a member of Helper that supersedes/replaces the showAccess map 
in  Helper.

-- Jon

From rick.hillegas at gmail.com  Tue Jul 12 01:28:46 2016
From: rick.hillegas at gmail.com (Rick Hillegas)
Date: Mon, 11 Jul 2016 18:28:46 -0700
Subject: primer for writing Java 9 taglets
Message-ID: <578447CE.1090701@gmail.com>

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

From jonathan.gibbons at oracle.com  Tue Jul 12 02:00:20 2016
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Mon, 11 Jul 2016 19:00:20 -0700
Subject: primer for writing Java 9 taglets
In-Reply-To: <578447CE.1090701@gmail.com>
References: <578447CE.1090701@gmail.com>
Message-ID: <57844F34.2040600@oracle.com>



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





From rick.hillegas at gmail.com  Wed Jul 13 01:45:48 2016
From: rick.hillegas at gmail.com (Rick Hillegas)
Date: Tue, 12 Jul 2016 18:45:48 -0700
Subject: primer for writing Java 9 taglets
In-Reply-To: <57844F34.2040600@oracle.com>
References: <578447CE.1090701@gmail.com> <57844F34.2040600@oracle.com>
Message-ID: <57859D4C.4080804@gmail.com>

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


From jonathan.gibbons at oracle.com  Wed Jul 13 02:22:19 2016
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Tue, 12 Jul 2016 19:22:19 -0700
Subject: primer for writing Java 9 taglets
In-Reply-To: <57859D4C.4080804@gmail.com>
References: <578447CE.1090701@gmail.com> <57844F34.2040600@oracle.com>
	<57859D4C.4080804@gmail.com>
Message-ID: <5785A5DB.4000708@oracle.com>



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.



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


From bhavesh.x.patel at oracle.com  Wed Jul 13 21:02:44 2016
From: bhavesh.x.patel at oracle.com (Bhavesh Patel)
Date: Wed, 13 Jul 2016 14:02:44 -0700
Subject: RFR: 8161255, jdk build "all" (docs) fails on all platforms, error
	from DefaultLoggerFinder.java
Message-ID: <5786AC74.8060805@oracle.com>

Hi,
      This is the fix for the issue in which the JDK API documentation 
build fails due to comment in DefaultLoggerFinder.java that points to a 
type in an unexported (internal) API. Doclint reports this is an error 
during the reference check and the documentation build fails. The 
makefile for javadoc needs to be updated to disable the reference check 
in the jdk.internal.logger package.

JBS: https://bugs.openjdk.java.net/browse/JDK-8161255
Webrev: http://cr.openjdk.java.net/~bpatel/8161255/webrev/

      Please review this change.

Thanks,
Bhavesh.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20160713/29a60229/attachment.html>

From joe.darcy at oracle.com  Wed Jul 13 21:05:08 2016
From: joe.darcy at oracle.com (joe darcy)
Date: Wed, 13 Jul 2016 14:05:08 -0700
Subject: RFR: 8161255, jdk build "all" (docs) fails on all platforms,
	error from DefaultLoggerFinder.java
In-Reply-To: <5786AC74.8060805@oracle.com>
References: <5786AC74.8060805@oracle.com>
Message-ID: <f747a8ae-6668-5828-f155-55b7087fddeb@oracle.com>

Hi Bhavesh,

This looks fine to get the build going again; please push this right away.

As we discussed off-list, there will probably need to be some additional 
javadoc mechanisms so that checking for this kind of implementation 
detail doesn't run afoul of doclint unnecessarily.

Thanks,

-Joe


On 7/13/2016 2:02 PM, Bhavesh Patel wrote:
> Hi,
>      This is the fix for the issue in which the JDK API documentation 
> build fails due to comment in DefaultLoggerFinder.java that points to 
> a type in an unexported (internal) API. Doclint reports this is an 
> error during the reference check and the documentation build fails. 
> The makefile for javadoc needs to be updated to disable the reference 
> check in the jdk.internal.logger package.
>
> JBS: https://bugs.openjdk.java.net/browse/JDK-8161255
> Webrev: http://cr.openjdk.java.net/~bpatel/8161255/webrev/
>
>      Please review this change.
>
> Thanks,
> Bhavesh.


From kumar.x.srinivasan at oracle.com  Wed Jul 13 21:05:05 2016
From: kumar.x.srinivasan at oracle.com (Kumar Srinivasan)
Date: Wed, 13 Jul 2016 14:05:05 -0700
Subject: RFR: 8161255, jdk build "all" (docs) fails on all platforms,
	error from DefaultLoggerFinder.java
In-Reply-To: <f747a8ae-6668-5828-f155-55b7087fddeb@oracle.com>
References: <5786AC74.8060805@oracle.com>
	<f747a8ae-6668-5828-f155-55b7087fddeb@oracle.com>
Message-ID: <5786AD01.8080005@oracle.com>

+1, I have also tested on Windows.

Kumar

On 7/13/2016 2:05 PM, joe darcy wrote:
> Hi Bhavesh,
>
> This looks fine to get the build going again; please push this right 
> away.
>
> As we discussed off-list, there will probably need to be some 
> additional javadoc mechanisms so that checking for this kind of 
> implementation detail doesn't run afoul of doclint unnecessarily.
>
> Thanks,
>
> -Joe
>
>
> On 7/13/2016 2:02 PM, Bhavesh Patel wrote:
>> Hi,
>>      This is the fix for the issue in which the JDK API documentation 
>> build fails due to comment in DefaultLoggerFinder.java that points to 
>> a type in an unexported (internal) API. Doclint reports this is an 
>> error during the reference check and the documentation build fails. 
>> The makefile for javadoc needs to be updated to disable the reference 
>> check in the jdk.internal.logger package.
>>
>> JBS: https://bugs.openjdk.java.net/browse/JDK-8161255
>> Webrev: http://cr.openjdk.java.net/~bpatel/8161255/webrev/
>>
>>      Please review this change.
>>
>> Thanks,
>> Bhavesh.
>


From tim.bell at oracle.com  Wed Jul 13 21:28:56 2016
From: tim.bell at oracle.com (Tim Bell)
Date: Wed, 13 Jul 2016 14:28:56 -0700
Subject: RFR: 8161255, jdk build "all" (docs) fails on all platforms,
	error from DefaultLoggerFinder.java
In-Reply-To: <5786AC74.8060805@oracle.com>
References: <5786AC74.8060805@oracle.com>
Message-ID: <5786B298.4030208@oracle.com>

Hi Bhavesh:

>      This is the fix for the issue in which the JDK API documentation 
> build fails due to comment in DefaultLoggerFinder.java that points to 
> a type in an unexported (internal) API. Doclint reports this is an 
> error during the reference check and the documentation build fails. 
> The makefile for javadoc needs to be updated to disable the reference 
> check in the jdk.internal.logger package.
>
> JBS: https://bugs.openjdk.java.net/browse/JDK-8161255
> Webrev: http://cr.openjdk.java.net/~bpatel/8161255/webrev/
>
>      Please review this change.

Looks good.  Approved.

Tim


From jonathan.gibbons at oracle.com  Wed Jul 13 21:42:43 2016
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 13 Jul 2016 14:42:43 -0700
Subject: RFR: 8161255, jdk build "all" (docs) fails on all platforms,
	error from DefaultLoggerFinder.java
In-Reply-To: <f747a8ae-6668-5828-f155-55b7087fddeb@oracle.com>
References: <5786AC74.8060805@oracle.com>
	<f747a8ae-6668-5828-f155-55b7087fddeb@oracle.com>
Message-ID: <5786B5D3.4010309@oracle.com>

Joe, all,

Work for javadoc support for modules is a work in progress.  While we 
should have caught yesterday's problems ahead of time, it will also be 
the case that as javadoc moves along, we will refine the contents of the 
module summary page, so that items which should not be documented are 
correctly omitted.

-- Jon


On 07/13/2016 02:05 PM, joe darcy wrote:
> Hi Bhavesh,
>
> This looks fine to get the build going again; please push this right 
> away.
>
> As we discussed off-list, there will probably need to be some 
> additional javadoc mechanisms so that checking for this kind of 
> implementation detail doesn't run afoul of doclint unnecessarily.
>
> Thanks,
>
> -Joe
>
>
> On 7/13/2016 2:02 PM, Bhavesh Patel wrote:
>> Hi,
>>      This is the fix for the issue in which the JDK API documentation 
>> build fails due to comment in DefaultLoggerFinder.java that points to 
>> a type in an unexported (internal) API. Doclint reports this is an 
>> error during the reference check and the documentation build fails. 
>> The makefile for javadoc needs to be updated to disable the reference 
>> check in the jdk.internal.logger package.
>>
>> JBS: https://bugs.openjdk.java.net/browse/JDK-8161255
>> Webrev: http://cr.openjdk.java.net/~bpatel/8161255/webrev/
>>
>>      Please review this change.
>>
>> Thanks,
>> Bhavesh.
>


From rick.hillegas at gmail.com  Sat Jul 16 15:30:51 2016
From: rick.hillegas at gmail.com (Rick Hillegas)
Date: Sat, 16 Jul 2016 15:30:51 -0000
Subject: primer for writing Java 9 taglets
In-Reply-To: <5785A5DB.4000708@oracle.com>
References: <578447CE.1090701@gmail.com>
	<57844F34.2040600@oracle.com>	<57859D4C.4080804@gmail.com>
	<5785A5DB.4000708@oracle.com>
Message-ID: <578A5326.1070603@gmail.com>

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


From rick.hillegas at gmail.com  Tue Jul 19 01:18:11 2016
From: rick.hillegas at gmail.com (Rick Hillegas)
Date: Mon, 18 Jul 2016 18:18:11 -0700
Subject: primer for writing Java 9 taglets
In-Reply-To: <578A5326.1070603@gmail.com>
References: <578447CE.1090701@gmail.com>
	<57844F34.2040600@oracle.com>	<57859D4C.4080804@gmail.com>
	<5785A5DB.4000708@oracle.com> <578A5326.1070603@gmail.com>
Message-ID: <578D7FD3.4040806@gmail.com>

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