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