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