JDK 9 RFR of JDK-8072734: Turn on doclint checking in the build of modules in the jdk repo
joe darcy
joe.darcy at oracle.com
Thu Mar 12 04:46:16 UTC 2015
Hi Jon,
On 3/11/2015 8:04 PM, Jonathan Gibbons wrote:
> Joe,
>
> This is excellent work.
Thank you. It builds on previous excellent work getting doclint into the
platform :-)
>
> Can I suggest that until we achieve perfection, we keep a status table
> somewhere listing the current level of goodness on a per-module basis,
> meaning, in a more digestible form than crawling through makefiles.
Hmm...
On a related note, I should have mentioned that the preferred way to
turn doclint on would to be modify
./common/SetupJavaCompilers.gmk
along the lines of
--- a/make/common/SetupJavaCompilers.gmk Wed Mar 11 08:25:55 2015 -0700
+++ b/make/common/SetupJavaCompilers.gmk Wed Mar 11 21:35:03 2015 -0700
@@ -32,7 +32,7 @@
# If warnings needs to be non-fatal for testing purposes use a command
like:
# make JAVAC_WARNINGS="-Xlint:all -Xmaxwarns 10000"
-JAVAC_WARNINGS := -Xlint:all -Werror
+JAVAC_WARNINGS := -Xlint:all -Werror -Xdoclint:all/protected
'-Xdoclint/package:java.*,javax.*'
# The BOOT_JAVAC setup uses the boot jdk compiler to compile the tools
# and the interim javac, to be run by the boot jdk.
which would set a consistently high level of doclint checking in one go
throughout the modules hosted in the jdk repo.
(For good measure, in time we could also include the non-internal parts
of the jdk.* package in the set of packages checked.)
Until the preconditions of getting one simple check in place are met,
the incremental approach is to have module-specific doclint settings
which can be adjusted up over time, as in the patch out for review.
Did you have a location in mind for such a table? Somewhere is the
source tree is preferable. If a better alternative doesn't present
itself, perhaps a comment in the CompileJavaModules.gmk file would be
better than nothing. For the patch sent out for review, I only updated
the command for modules which already had some sort of customized
handling and I doubt all modules where covered. However, I suspect the
majority of the code in the jdk repo is in either the java.base or
java.desktop module so those alone represent most of the API surface.
Thanks,
-Joe
>
> -- Jon
>
> On 03/11/2015 07:53 PM, joe darcy wrote:
>> Hello,
>>
>> With package filtering of doclint checking now available
>> (JDK-8071851: Provide filtering of doclint checking based on
>> packages), the time has come to enable a subset of doclint checking
>> in the main build for java.* and javax.* packages.
>>
>> First, there is the simple subtask of doing this for the relevant
>> files hosted in the langtools repository (JDK-8075035: Turn on
>> doclint checking of modules in the langtools repo):
>>
>> diff -r 072008f47620 make/build.properties
>> --- a/make/build.properties Wed Mar 11 22:24:05 2015 +0100
>> +++ b/make/build.properties Wed Mar 11 19:32:58 2015 -0700
>> @@ -28,7 +28,7 @@
>> javac.debuglevel = source,lines,vars
>> javac.extra.opts=-XDignore.symbol.file=true
>> javac.includes=
>> -javac.lint.opts = -Xlint:all,-deprecation -Werror
>> +javac.lint.opts = -Xlint:all,-deprecation -Xdoclint:all/protected
>> '-Xdoclint/package:java.*,javax.*' -Werror
>> javac.source = 8
>> javac.target = 8
>>
>> Next are the more extensive changes for modules in the jdk repo:
>>
>> JDK-8072734 : Turn on doclint checking in the build of modules in
>> the jdk repo
>> http://cr.openjdk.java.net/~darcy/8072734.0/
>>
>> Full patch below. A few notes on the checks excluded from doclint
>> checking. In the desktop module, there are still hundreds of method
>> with missing javadoc (JDK-8071630) and the "missing" check cannot be
>> enabled until that javadoc is added.
>>
>> The javadoc of the base module contains a few @see or @link
>> references to members outside of the base module. Those outside
>> members are not currently visible to javac when the base module is
>> being compiled. That may change at some point later in JDK 9. If and
>> when it does, the "reference" check can be enabled.
>>
>> In the desktop module some generated files are referencing other
>> types in javadoc that aren't visible at that point. A later build
>> change may be able to address this.
>>
>> There are five categories of doclint checks so my strong preference
>> is to get a subset of checks enabled in the build and then work on
>> enabling the remaining ones later on.
>>
>> With the application of a javadoc fix in the jdk repo I have out for
>> review (JDK-8075034), a local build with the langtools and jdk-repo
>> module checks has succeeded. To apply all due caution, upon
>> successful review, I will have a jprt job submitted to push this
>> change to verify there are no unexpected platform dependencies that
>> would cause a build failure.
>>
>> To be clear, with this set of changes, it will be a true build error
>> if certain categories of doclint problems is introduced to a java.*
>> or javax.* type. This would be a large step toward completing the
>> remaining goals of JEP 212: Resolve Lint and Doclint Warnings.
>>
>> Thanks,
>>
>> Thanks,
>>
>> -Joe
>>
>> --- old/make/CompileJavaModules.gmk 2015-03-11 19:39:09.884348698
>> -0700
>> +++ new/make/CompileJavaModules.gmk 2015-03-11 19:39:09.796304698
>> -0700
>> @@ -42,6 +42,7 @@
>>
>> ################################################################################
>>
>>
>> +java.base_ADD_JAVAC_FLAGS := -Xdoclint:all/protected,-reference
>> '-Xdoclint/package:java.*,javax.*'
>> java.base_COPY := .icu .dat .spp content-types.properties
>> hijrah-config-islamic-umalqura.properties
>> java.base_CLEAN := intrinsic.properties
>>
>> @@ -89,10 +90,12 @@
>>
>> ################################################################################
>>
>>
>> +java.datatransfer_ADD_JAVAC_FLAGS :=
>> -Xdoclint:all/protected,-reference '-Xdoclint/package:java.*,javax.*'
>> java.datatransfer_COPY := flavormap.properties
>>
>> ################################################################################
>>
>>
>> +java.desktop_ADD_JAVAC_FLAGS :=
>> -Xdoclint:all/protected,-missing,-reference
>> '-Xdoclint/package:java.*,javax.*'
>> java.desktop_COPY := .gif .png .wav .txt .xml .css .pf
>> java.desktop_CLEAN := iio-plugin.properties cursors.properties
>>
>> @@ -239,15 +242,18 @@
>>
>> ################################################################################
>>
>>
>> +java.scripting_ADD_JAVAC_FLAGS := -Xdoclint:all/protected
>> '-Xdoclint/package:java.*,javax.*'
>> java.scripting_COPY := .js
>> java.scripting_CLEAN := .properties
>>
>> ################################################################################
>>
>>
>> +java.sql_ADD_JAVAC_FLAGS := -Xdoclint:all/protected
>> '-Xdoclint/package:java.*,javax.*'
>> java.sql_SETUP := GENERATE_JDKBYTECODE_NOWARNINGS
>>
>> ################################################################################
>>
>>
>> +java.sql.rowset_ADD_JAVAC_FLAGS := -Xdoclint:all/protected
>> '-Xdoclint/package:java.*,javax.*'
>> java.sql.rowset_CLEAN_FILES := $(wildcard \
>> $(JDK_TOPDIR)/src/java.sql.rowset/share/classes/com/sun/rowset/*.properties
>> \
>> $(JDK_TOPDIR)/src/java.sql.rowset/share/classes/javax/sql/rowset/*.properties)
>>
>> @@ -261,6 +267,7 @@
>>
>> ################################################################################
>>
>>
>> +java.rmi_ADD_JAVAC_FLAGS := -Xdoclint:all/protected
>> '-Xdoclint/package:java.*,javax.*'
>> java.rmi_CLEAN_FILES := $(wildcard \
>> $(JDK_TOPDIR)/src/java.rmi/share/classes/sun/rmi/registry/resources/*.properties
>> \
>> $(JDK_TOPDIR)/src/java.rmi/share/classes/sun/rmi/server/resources/*.properties)
>>
>> @@ -309,14 +316,17 @@
>>
>> ################################################################################
>>
>>
>> +java.naming_ADD_JAVAC_FLAGS := -Xdoclint:all/protected
>> '-Xdoclint/package:java.*,javax.*'
>> java.naming_CLEAN := jndiprovider.properties
>>
>> ################################################################################
>>
>>
>> +java.security.saaj_ADD_JAVAC_FLAGS := -Xdoclint:all/protected
>> '-Xdoclint/package:java.*,javax.*'
>> java.security.saaj_CLEAN := .properties
>>
>> ################################################################################
>>
>>
>> +java.xml.crypto_ADD_JAVAC_FLAGS := -Xdoclint:all/protected
>> '-Xdoclint/package:java.*,javax.*'
>> java.xml.crypto_COPY := .dtd .xml
>> java.xml.crypto_CLEAN := .properties
>>
>> @@ -485,7 +495,7 @@
>> $1_CLASSPATH := $$($1_CLASSPATH) $$(addprefix
>> $(JDK_OUTPUTDIR)/modules/,jdk.hotspot.agent)
>> endif
>> $1_CLASSPATH := $$(subst $$(SPACE),$$(PATH_SEP),$$($1_CLASSPATH))
>> - $1_JAVAC_FLAGS := -bootclasspath "$$($1_CLASSPATH)"
>> + $1_JAVAC_FLAGS := -bootclasspath "$$($1_CLASSPATH)"
>> $$($1_ADD_JAVAC_FLAGS)
>>
>> $$(eval $$(call SetupJavaCompilation,$1, \
>> SETUP := $$(if $$($1_SETUP), $$($1_SETUP),
>> GENERATE_JDKBYTECODE), \
>>
>
More information about the build-dev
mailing list