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

Thu Mar 12 02:53:06 UTC 2015

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


