JDK 9 RFR of JDK-8072734: Turn on doclint checking in the build of modules in the jdk repo

Thu Mar 12 03:04:40 UTC 2015

Joe,

This is excellent work.

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.

-- 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), \
>