JDK 9 RFR of JDK-8031081 Use separate doclint flags for different doc bundles

[Tim Bell]

Hi Joe

On 12/31/13 01:24 AM, Chris Hegarty wrote:
> Makes sense to me. The changes look fine.

Looks good to me as well.

Tim

> -Chris
>
>> On 31 Dec 2013, at 02:07, Joe Darcy <joe.darcy at oracle.com> wrote:
>>
>> Hello,
>>
>> Starting in JDK 8, there have been efforts to clean up the doclint warnings and errors, especially for types going into the coredocs bundle. The core libraries are doclint clean and much progress has been made on the client area. I'll soon have a patch out for review that will clear all the doclint problems in three of the five doclint categories in client, meaning several categories of doclint checks will be able to be turned on for the whole core docs bundle :-)
>>
>> However, not all of the sources used to build the ~15 docs bundles have been cleaned to the same degree and they should be expected to be cleaned at different rates. Therefore, until all the bundles have been cleared of all problems, I think the commands to make each bundle should have its own doclint option so they can be tightened independently.
>>
>> To be clear, the goal would be for "-Xdoclint:all/protected" to be used on all bundles.
>>
>> In the mean time, please review the patch below which introduces a separate doclint option for each bundle.
>>
>> Thanks,
>>
>> -Joeg
>>
>> diff -r bd254db01a0e make/Javadoc.gmk
>> --- a/make/Javadoc.gmk    Thu Dec 19 14:11:12 2013 +0100
>> +++ b/make/Javadoc.gmk    Mon Dec 30 18:06:02 2013 -0800
>> @@ -265,7 +265,6 @@
>>      -quiet \
>>      -use \
>>      -keywords \
>> -    -Xdoclint:none \
>>      -Xprofilespath $(JDK_TOPDIR)/make/profile-rtjar-includes.txt \
>>      $(ADDITIONAL_JAVADOCFLAGS)
>>
>> @@ -381,6 +380,7 @@
>> $(COREAPI_OPTIONS_FILE): $(COREAPI_OVERVIEW)
>>      $(prep-target)
>>      @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
>> +      $(call OptionOnly,-Xdoclint:none) ; \
>>        $(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
>>        $(call OptionPair,-encoding,ISO-8859-1) ; \
>>        $(call OptionPair,-tag,beaninfo:X) ; \
>> @@ -456,6 +456,7 @@
>> $(DOCLETAPI_OPTIONS_FILE):
>>      $(prep-target)
>>      @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
>> +      $(call OptionOnly,-Xdoclint:none) ; \
>>        $(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
>>        $(call OptionPair,-encoding,ascii) ; \
>>        $(call OptionOnly,-breakiterator) ; \
>> @@ -512,6 +513,7 @@
>> $(TAGLETAPI_OPTIONS_FILE):
>>      $(prep-target)
>>      @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
>> +      $(call OptionOnly,-Xdoclint:none) ; \
>>        $(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
>>        $(call OptionPair,-encoding,ascii) ; \
>>        $(call OptionOnly,-nonavbar) ; \
>> @@ -563,6 +565,7 @@
>> $(DOMAPI_OPTIONS_FILE):
>>      $(prep-target)
>>      @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
>> +      $(call OptionOnly,-Xdoclint:none) ; \
>>        $(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
>>        $(call OptionPair,-encoding,ascii) ; \
>>        $(call OptionOnly,-splitIndex) ; \
>> @@ -625,6 +628,7 @@
>> $(JDI_OPTIONS_FILE): $(JDI_OVERVIEW)
>>      $(prep-target)
>>      @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
>> +      $(call OptionOnly,-Xdoclint:none) ; \
>>        $(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
>>        $(call OptionPair,-encoding,ascii) ; \
>>        $(call OptionPair,-overview,$(JDI_OVERVIEW)) ; \
>> @@ -712,6 +716,7 @@
>> $(JAAS_OPTIONS_FILE): $(JAAS_OVERVIEW)
>>      $(prep-target)
>>      @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
>> +      $(call OptionOnly,-Xdoclint:none) ; \
>>        $(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
>>        $(call OptionPair,-encoding,ascii) ; \
>>        $(call OptionPair,-overview,$(JAAS_OVERVIEW)) ; \
>> @@ -764,6 +769,7 @@
>> $(JGSS_OPTIONS_FILE): $(JGSS_OVERVIEW)
>>      $(prep-target)
>>      @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
>> +      $(call OptionOnly,-Xdoclint:none) ; \
>>        $(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
>>        $(call OptionPair,-encoding,ascii) ; \
>>        $(call OptionOnly,-nodeprecatedlist) ; \
>> @@ -816,6 +822,7 @@
>> $(SMARTCARDIO_OPTIONS_FILE):
>>      $(prep-target)
>>      @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
>> +      $(call OptionOnly,-Xdoclint:none) ; \
>>        $(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
>>        $(call OptionPair,-encoding,ascii) ; \
>>        $(call OptionOnly,-nodeprecatedlist) ; \
>> @@ -866,6 +873,7 @@
>> $(HTTPSERVER_OPTIONS_FILE):
>>      $(prep-target)
>>      @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
>> +      $(call OptionOnly,-Xdoclint:none) ; \
>>        $(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
>>        $(call OptionPair,-encoding,ascii) ; \
>>        $(call OptionOnly,-nodeprecatedlist) ; \
>> @@ -926,6 +934,7 @@
>> $(MGMT_OPTIONS_FILE): $(MGMT_OVERVIEW)
>>      $(prep-target)
>>      @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
>> +      $(call OptionOnly,-Xdoclint:none) ; \
>>        $(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
>>        $(call OptionPair,-encoding,ascii) ; \
>>        $(call OptionOnly,-nodeprecatedlist) ; \
>> @@ -977,6 +986,7 @@
>> $(ATTACH_OPTIONS_FILE):
>>      $(prep-target)
>>      @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
>> +      $(call OptionOnly,-Xdoclint:none) ; \
>>        $(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
>>        $(call OptionPair,-encoding,ascii) ; \
>>        $(call OptionOnly,-nodeprecatedlist) ; \
>> @@ -1027,6 +1037,7 @@
>> $(JCONSOLE_OPTIONS_FILE):
>>      $(prep-target)
>>      @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
>> +      $(call OptionOnly,-Xdoclint:none) ; \
>>        $(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
>>        $(call OptionPair,-encoding,ascii) ; \
>>        $(call OptionOnly,-nodeprecatedlist) ; \
>> @@ -1079,6 +1090,7 @@
>> $(TREEAPI_OPTIONS_FILE):
>>      $(prep-target)
>>      @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
>> +      $(call OptionOnly,-Xdoclint:none) ; \
>>        $(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
>>        $(call OptionPair,-encoding,ascii) ; \
>>        $(call OptionPair,-doctitle,$(TREEAPI_DOCTITLE)) ; \
>> @@ -1130,6 +1142,7 @@
>> $(SCTPAPI_OPTIONS_FILE):
>>      $(prep-target)
>>      @($(call OptionOnly,$(COMMON_JAVADOCFLAGS)) ; \
>> +      $(call OptionOnly,-Xdoclint:none) ; \
>>        $(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
>>        $(call OptionPair,-encoding,ascii) ; \
>>        $(call OptionOnly,-nodeprecatedlist) ; \
>>