8189056: javadoc target for stable specdiff comparisons

Reviewed-by: erikj
This commit is contained in:
Magnus Ihse Bursie 2017-10-23 10:21:13 +02:00
parent 6f51392180
commit 6d882e45a4
5 changed files with 234 additions and 31 deletions

View File

@ -97,6 +97,11 @@ JAVADOC_TAGS := \
$(CUSTOM_JAVADOC_TAGS) \
#
# The reference tags must stay stable to allow for comparisons across the
# development cycle. If JAVADOC_TAGS needs to change, make sure that
# REFERENCE_TAGS remains unchanged, by copying and hardcoding, if necessary.
REFERENCE_TAGS := $(JAVADOC_TAGS)
# Which doclint checks to ignore
JAVADOC_DISABLED_DOCLINT := accessibility html missing syntax reference
@ -106,6 +111,12 @@ JAVADOC_OPTIONS := -use -keywords -notimestamp \
-splitIndex --system none -html5 -javafx --expand-requires transitive \
--override-methods=summary
# The reference options must stay stable to allow for comparisons across the
# development cycle.
REFERENCE_OPTIONS := -XDignore.symbol.file=true -use -keywords -notimestamp \
-serialwarn -encoding ISO-8859-1 -breakiterator -splitIndex --system none \
-html5 -javafx --expand-requires transitive
# Should we add DRAFT stamps to the generated javadoc?
ifeq ($(VERSION_IS_GA), true)
IS_DRAFT := false
@ -130,6 +141,11 @@ ifeq ($(IS_DRAFT), true)
endif
DRAFT_TEXT := This specification is not final and is subject to change. \
Use is subject to <a href="$(LICENSE_URL)">license terms</a>.
# Workaround stylesheet bug
HEADER_STYLE := style="margin-top: 9px;"
else
HEADER_STYLE := style="margin-top: 14px;"
endif
JAVADOC_BOTTOM := \
@ -148,12 +164,19 @@ JAVADOC_BOTTOM := \
<a href="$(REDISTRIBUTION_URL)">documentation redistribution policy</a>. \
$(DRAFT_MARKER_STR) <!-- Version $(VERSION_STRING) -->
JAVADOC_TOP := \
<div style="padding: 6px; text-align: center; font-size: 80%; \
font-family: DejaVu Sans, Arial, Helvetica, sans-serif; \
font-weight: normal;">$(DRAFT_TEXT)</div>
JDK_INDEX_CONTENT := \
<!DOCTYPE html> \
<html lang="en"> \
<head> \
<meta http-equiv="refresh" content="0;url=api/index.html"> \
</head> \
</html>
################################################################################
# JDK javadoc titles/text snippets
@ -258,8 +281,14 @@ define SetupApiDocsGenerationBody
$1_JAVA_ARGS += -DenableModuleGraph=true
endif
# Always include tags and basic options
$1_OPTIONS := $$(JAVADOC_TAGS) $$(JAVADOC_OPTIONS)
# Start with basic options and tags
ifeq ($$($1_OPTIONS), )
$1_OPTIONS := $$(JAVADOC_OPTIONS)
endif
ifeq ($$($1_TAGS), )
$1_TAGS := $$(JAVADOC_TAGS)
endif
$1_OPTIONS += $$($1_TAGS)
$1_OPTIONS += --module-source-path $$(MODULES_SOURCE_PATH)
$1_OPTIONS += --module $$(call CommaList, $$($1_MODULES))
@ -268,15 +297,10 @@ define SetupApiDocsGenerationBody
$1_OPTIONS += -Xdoclint:all,$$(call CommaList, $$(addprefix -, \
$$(JAVADOC_DISABLED_DOCLINT)))
$1_DOC_TITLE := $$($1_LONG_NAME)<br>Version $$(VERSION_SPECIFICATION) API Specification
$1_WINDOW_TITLE := $$(subst &amp;,&,$$($1_SHORT_NAME)) \
$$(DRAFT_MARKER_TITLE)
ifeq ($(VERSION_IS_GA), true) # Workaround stylesheet bug
$1_HEADER_PAD := 14
else
$1_HEADER_PAD := 9
endif
$1_HEADER_TITLE := <div style="margin-top: $$($1_HEADER_PAD)px;"><strong>$$($1_SHORT_NAME)</strong> \
$1_DOC_TITLE := $$($1_LONG_NAME)<br>Version $$(VERSION_SPECIFICATION) API \
Specification
$1_WINDOW_TITLE := $$(subst &amp;,&,$$($1_SHORT_NAME)) $$(DRAFT_MARKER_TITLE)
$1_HEADER_TITLE := <div $$(HEADER_STYLE)><strong>$$($1_SHORT_NAME)</strong> \
$$(DRAFT_MARKER_STR)</div>
$1_OPTIONS += -doctitle '$$($1_DOC_TITLE)'
@ -303,8 +327,13 @@ define SetupApiDocsGenerationBody
$$(eval $1_OPTIONS += -group "$$($$g_GROUP_NAME)" "$$($$g_GROUP_MODULES)") \
)
ifeq ($$($1_JAVADOC_CMD), )
$1_JAVADOC_CMD := $$(JAVA) -Djava.awt.headless=true $$($1_JAVA_ARGS) \
$$(NEW_JAVADOC)
endif
$1_VARDEPS := $$($1_JAVA_ARGS) $$($1_OPTIONS) $$(MODULES_SOURCE_PATH) \
$$($1_ALL_MODULES)
$$($1_ALL_MODULES) $$($1_JAVADOC_CMD)
$1_VARDEPS_FILE := $$(call DependOnVariable, $1_VARDEPS, \
$$(SUPPORT_OUTPUTDIR)/docs/$1.vardeps)
@ -320,9 +349,8 @@ define SetupApiDocsGenerationBody
$$(call LogInfo, Javadoc modules: $$($1_ALL_MODULES))
$$(call MakeDir, $$($1_TARGET_DIR))
$$(call ExecuteWithLog, $$(SUPPORT_OUTPUTDIR)/docs/$1, \
$$(JAVA) -Djava.awt.headless=true $$($1_JAVA_ARGS) \
$$(NEW_JAVADOC) -d $$($1_TARGET_DIR) \
$$(JAVADOC_TAGS) $$($1_OPTIONS) $$($1_LOG_OPTION))
$$($1_JAVADOC_CMD) -d $$($1_TARGET_DIR) \
$$($1_OPTIONS) $$($1_LOG_OPTION))
$1_JAVADOC_TARGETS := $$($1_TARGET_DIR)/index.html
@ -431,19 +459,30 @@ $(eval $(call SetupApiDocsGeneration, JAVASE_API, \
# Targets generated are returned in JAVASE_API_JAVADOC_TARGETS and
# JAVASE_API_MODULEGRAPH_TARGETS.
################################################################################
# Setup generation of the reference Java SE API documentation (javadoc + modulegraph)
# The reference javadoc is just the same as javase, but using the BootJDK javadoc
# and a stable set of javadoc options.
$(eval $(call SetupApiDocsGeneration, REFERENCE_API, \
MODULES := $(JAVASE_MODULES), \
SHORT_NAME := $(JAVASE_SHORT_NAME), \
LONG_NAME := $(JAVASE_LONG_NAME), \
TARGET_DIR := $(IMAGES_OUTPUTDIR)/reference-docs/api, \
JAVADOC_CMD := $(JAVADOC), \
OPTIONS := $(REFERENCE_OPTIONS), \
TAGS := $(REFERENCE_TAGS), \
))
# Targets generated are returned in REFERENCE_API_JAVADOC_TARGETS and
# REFERENCE_API_MODULEGRAPH_TARGETS.
################################################################################
JDK_INDEX_HTML := $(DOCS_OUTPUTDIR)/index.html
JDK_INDEX_CONTENT := \
<!DOCTYPE html> \
<html lang="en"> \
<head> \
<meta http-equiv="refresh" content="0;url=api/index.html"> \
</head> \
</html>
$(JDK_INDEX_HTML):
$(JDK_INDEX_HTML):
$(ECHO) '$(JDK_INDEX_CONTENT)' > $@
JDK_INDEX_TARGETS += $(JDK_INDEX_HTML)
@ -554,6 +593,10 @@ docs-javase-api-javadoc: $(JAVASE_API_JAVADOC_TARGETS) $(JAVASE_API_CUSTOM_TARGE
docs-javase-api-modulegraph: $(JAVASE_API_MODULEGRAPH_TARGETS)
docs-reference-api-javadoc: $(REFERENCE_API_JAVADOC_TARGETS) $(REFERENCE_API_CUSTOM_TARGETS)
docs-reference-api-modulegraph: $(REFERENCE_API_MODULEGRAPH_TARGETS)
docs-jdk-specs: $(JDK_SPECS_TARGETS)
docs-jdk-index: $(JDK_INDEX_TARGETS)
@ -561,8 +604,10 @@ docs-jdk-index: $(JDK_INDEX_TARGETS)
docs-zip: $(ZIP_TARGETS)
all: docs-jdk-api-javadoc docs-jdk-api-modulegraph docs-javase-api-javadoc \
docs-javase-api-modulegraph docs-jdk-specs docs-jdk-index docs-zip
docs-javase-api-modulegraph docs-reference-api-javadoc \
docs-reference-api-modulegraph docs-jdk-specs docs-jdk-index docs-zip
.PHONY: default all docs-jdk-api-javadoc docs-jdk-api-modulegraph \
docs-javase-api-javadoc docs-javase-api-modulegraph docs-jdk-specs \
docs-javase-api-javadoc docs-javase-api-modulegraph \
docs-reference-api-javadoc docs-reference-api-modulegraph docs-jdk-specs \
docs-jdk-index docs-zip

View File

@ -382,6 +382,12 @@ docs-javase-api-javadoc:
docs-javase-api-modulegraph:
+($(CD) $(TOPDIR)/make && $(MAKE) $(MAKE_ARGS) -f Docs.gmk docs-javase-api-modulegraph)
docs-reference-api-javadoc:
+($(CD) $(TOPDIR)/make && $(MAKE) $(MAKE_ARGS) -f Docs.gmk docs-reference-api-javadoc)
docs-reference-api-modulegraph:
+($(CD) $(TOPDIR)/make && $(MAKE) $(MAKE_ARGS) -f Docs.gmk docs-reference-api-modulegraph)
docs-jdk-specs:
+($(CD) $(TOPDIR)/make && $(MAKE) $(MAKE_ARGS) -f Docs.gmk docs-jdk-specs)
@ -395,7 +401,8 @@ update-build-docs:
+($(CD) $(TOPDIR)/make && $(MAKE) $(MAKE_ARGS) -f UpdateBuildDocs.gmk)
ALL_TARGETS += docs-jdk-api-javadoc docs-jdk-api-modulegraph \
docs-javase-api-javadoc docs-javase-api-modulegraph docs-jdk-specs \
docs-javase-api-javadoc docs-javase-api-modulegraph \
docs-reference-api-javadoc docs-reference-api-modulegraph docs-jdk-specs \
docs-jdk-index docs-zip update-build-docs
################################################################################
@ -810,10 +817,14 @@ else
docs-javase-api-javadoc: $(GENSRC_TARGETS) rmic
docs-reference-api-javadoc: $(GENSRC_TARGETS) rmic
docs-jdk-api-modulegraph: exploded-image buildtools-modules
docs-javase-api-modulegraph: exploded-image buildtools-modules
docs-reference-api-modulegraph: exploded-image buildtools-modules
# The gensrc steps for hotspot and jdk.jdi create html spec files.
docs-jdk-specs: hotspot-$(JVM_VARIANT_MAIN)-gensrc jdk.jdi-gensrc \
docs-jdk-index
@ -943,16 +954,19 @@ create-buildjdk: create-buildjdk-copy create-buildjdk-interim-image
docs-jdk-api: docs-jdk-api-javadoc
docs-javase-api: docs-javase-api-javadoc
docs-reference-api: docs-reference-api-javadoc
# If we're building full docs, we must also generate the module graphs to
# get non-broken api documentation.
ifeq ($(ENABLE_FULL_DOCS), true)
docs-jdk-api: docs-jdk-api-modulegraph
docs-javase-api: docs-javase-api-modulegraph
docs-reference-api: docs-reference-api-modulegraph
endif
docs-jdk: docs-jdk-api docs-jdk-specs docs-jdk-index
docs-javase: docs-javase-api
docs-reference: docs-reference-api
# alias for backwards compatibility
docs-javadoc: docs-jdk-api
@ -1005,8 +1019,8 @@ ALL_TARGETS += buildtools hotspot hotspot-libs hotspot-gensrc gensrc gendata \
copy java rmic libs launchers jmods \
jdk.jdwp.agent-gensrc $(ALL_MODULES) demos \
exploded-image-base exploded-image \
create-buildjdk docs-jdk-api docs-javase-api docs-jdk docs-javase \
docs-javadoc mac-bundles product-images \
create-buildjdk docs-jdk-api docs-javase-api docs-reference-api docs-jdk \
docs-javase docs-reference docs-javadoc mac-bundles product-images \
profiles profiles-images \
docs-image test-image all-images \
all-bundles

View File

@ -296,6 +296,7 @@ AC_DEFUN_ONCE([BOOTJDK_SETUP_BOOT_JDK],
BOOTJDK_CHECK_TOOL_IN_BOOTJDK(JAVA, java)
BOOTJDK_CHECK_TOOL_IN_BOOTJDK(JAVAC, javac)
BOOTJDK_CHECK_TOOL_IN_BOOTJDK(JAVAH, javah)
BOOTJDK_CHECK_TOOL_IN_BOOTJDK(JAVADOC, javadoc)
BOOTJDK_CHECK_TOOL_IN_BOOTJDK(JAR, jar)
BOOTJDK_CHECK_TOOL_IN_BOOTJDK(JARSIGNER, jarsigner)

View File

@ -881,6 +881,7 @@ JAVAC_FLAGS
BOOT_JDK_SOURCETARGET
JARSIGNER
JAR
JAVADOC
JAVAH
JAVAC
JAVA
@ -1294,6 +1295,7 @@ PKG_CONFIG
JAVA
JAVAC
JAVAH
JAVADOC
JAR
JARSIGNER
CC
@ -2237,6 +2239,7 @@ Some influential environment variables:
JAVA Override default value for JAVA
JAVAC Override default value for JAVAC
JAVAH Override default value for JAVAH
JAVADOC Override default value for JAVADOC
JAR Override default value for JAR
JARSIGNER Override default value for JARSIGNER
CC C compiler command
@ -5114,7 +5117,7 @@ VS_SDK_PLATFORM_NAME_2013=
#CUSTOM_AUTOCONF_INCLUDE
# Do not change or remove the following line, it is needed for consistency checks:
DATE_WHEN_GENERATED=1508497666
DATE_WHEN_GENERATED=1508746828
###############################################################################
#
@ -31169,6 +31172,144 @@ $as_echo "$tool_specified" >&6; }
# Use user overridden value if available, otherwise locate tool in the Boot JDK.
# Publish this variable in the help.
if [ -z "${JAVADOC+x}" ]; then
# The variable is not set by user, try to locate tool using the code snippet
{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for javadoc in Boot JDK" >&5
$as_echo_n "checking for javadoc in Boot JDK... " >&6; }
JAVADOC=$BOOT_JDK/bin/javadoc
if test ! -x $JAVADOC; then
{ $as_echo "$as_me:${as_lineno-$LINENO}: result: not found" >&5
$as_echo "not found" >&6; }
{ $as_echo "$as_me:${as_lineno-$LINENO}: Your Boot JDK seems broken. This might be fixed by explicitly setting --with-boot-jdk" >&5
$as_echo "$as_me: Your Boot JDK seems broken. This might be fixed by explicitly setting --with-boot-jdk" >&6;}
as_fn_error $? "Could not find javadoc in the Boot JDK" "$LINENO" 5
fi
{ $as_echo "$as_me:${as_lineno-$LINENO}: result: ok" >&5
$as_echo "ok" >&6; }
else
# The variable is set, but is it from the command line or the environment?
# Try to remove the string !JAVADOC! from our list.
try_remove_var=${CONFIGURE_OVERRIDDEN_VARIABLES//!JAVADOC!/}
if test "x$try_remove_var" = "x$CONFIGURE_OVERRIDDEN_VARIABLES"; then
# If it failed, the variable was not from the command line. Ignore it,
# but warn the user (except for BASH, which is always set by the calling BASH).
if test "xJAVADOC" != xBASH; then
{ $as_echo "$as_me:${as_lineno-$LINENO}: WARNING: Ignoring value of JAVADOC from the environment. Use command line variables instead." >&5
$as_echo "$as_me: WARNING: Ignoring value of JAVADOC from the environment. Use command line variables instead." >&2;}
fi
# Try to locate tool using the code snippet
{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for javadoc in Boot JDK" >&5
$as_echo_n "checking for javadoc in Boot JDK... " >&6; }
JAVADOC=$BOOT_JDK/bin/javadoc
if test ! -x $JAVADOC; then
{ $as_echo "$as_me:${as_lineno-$LINENO}: result: not found" >&5
$as_echo "not found" >&6; }
{ $as_echo "$as_me:${as_lineno-$LINENO}: Your Boot JDK seems broken. This might be fixed by explicitly setting --with-boot-jdk" >&5
$as_echo "$as_me: Your Boot JDK seems broken. This might be fixed by explicitly setting --with-boot-jdk" >&6;}
as_fn_error $? "Could not find javadoc in the Boot JDK" "$LINENO" 5
fi
{ $as_echo "$as_me:${as_lineno-$LINENO}: result: ok" >&5
$as_echo "ok" >&6; }
else
# If it succeeded, then it was overridden by the user. We will use it
# for the tool.
# First remove it from the list of overridden variables, so we can test
# for unknown variables in the end.
CONFIGURE_OVERRIDDEN_VARIABLES="$try_remove_var"
# Check if we try to supply an empty value
if test "x$JAVADOC" = x; then
{ $as_echo "$as_me:${as_lineno-$LINENO}: Setting user supplied tool JAVADOC= (no value)" >&5
$as_echo "$as_me: Setting user supplied tool JAVADOC= (no value)" >&6;}
{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for JAVADOC" >&5
$as_echo_n "checking for JAVADOC... " >&6; }
{ $as_echo "$as_me:${as_lineno-$LINENO}: result: disabled" >&5
$as_echo "disabled" >&6; }
else
# Check if the provided tool contains a complete path.
tool_specified="$JAVADOC"
tool_basename="${tool_specified##*/}"
if test "x$tool_basename" = "x$tool_specified"; then
# A command without a complete path is provided, search $PATH.
{ $as_echo "$as_me:${as_lineno-$LINENO}: Will search for user supplied tool JAVADOC=$tool_basename" >&5
$as_echo "$as_me: Will search for user supplied tool JAVADOC=$tool_basename" >&6;}
# Extract the first word of "$tool_basename", so it can be a program name with args.
set dummy $tool_basename; ac_word=$2
{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
$as_echo_n "checking for $ac_word... " >&6; }
if ${ac_cv_path_JAVADOC+:} false; then :
$as_echo_n "(cached) " >&6
else
case $JAVADOC in
[\\/]* | ?:[\\/]*)
ac_cv_path_JAVADOC="$JAVADOC" # Let the user override the test with a path.
;;
*)
as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
for as_dir in $PATH
do
IFS=$as_save_IFS
test -z "$as_dir" && as_dir=.
for ac_exec_ext in '' $ac_executable_extensions; do
if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
ac_cv_path_JAVADOC="$as_dir/$ac_word$ac_exec_ext"
$as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
break 2
fi
done
done
IFS=$as_save_IFS
;;
esac
fi
JAVADOC=$ac_cv_path_JAVADOC
if test -n "$JAVADOC"; then
{ $as_echo "$as_me:${as_lineno-$LINENO}: result: $JAVADOC" >&5
$as_echo "$JAVADOC" >&6; }
else
{ $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
$as_echo "no" >&6; }
fi
if test "x$JAVADOC" = x; then
as_fn_error $? "User supplied tool $tool_basename could not be found" "$LINENO" 5
fi
else
# Otherwise we believe it is a complete path. Use it as it is.
{ $as_echo "$as_me:${as_lineno-$LINENO}: Will use user supplied tool JAVADOC=$tool_specified" >&5
$as_echo "$as_me: Will use user supplied tool JAVADOC=$tool_specified" >&6;}
{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for JAVADOC" >&5
$as_echo_n "checking for JAVADOC... " >&6; }
if test ! -x "$tool_specified"; then
{ $as_echo "$as_me:${as_lineno-$LINENO}: result: not found" >&5
$as_echo "not found" >&6; }
as_fn_error $? "User supplied tool JAVADOC=$tool_specified does not exist or is not executable" "$LINENO" 5
fi
{ $as_echo "$as_me:${as_lineno-$LINENO}: result: $tool_specified" >&5
$as_echo "$tool_specified" >&6; }
fi
fi
fi
fi
# Use user overridden value if available, otherwise locate tool in the Boot JDK.
# Publish this variable in the help.

View File

@ -532,6 +532,7 @@ SJAVAC_SERVER_JAVA_FLAGS:=@SJAVAC_SERVER_JAVA_FLAGS@
JAVA_CMD:=@JAVA@
JAVAC_CMD:=@JAVAC@
JAVAH_CMD:=@JAVAH@
JAVADOC_CMD:=@JAVADOC@
JAR_CMD:=@JAR@
JLINK_CMD := @JLINK@
JMOD_CMD := @JMOD@
@ -544,6 +545,7 @@ JAVA_SMALL=@FIXPATH@ $(JAVA_CMD) $(JAVA_FLAGS_SMALL) $(JAVA_FLAGS)
JAVA_JAVAC=@FIXPATH@ $(JAVA_CMD) $(JAVA_FLAGS_JAVAC) $(JAVA_FLAGS)
JAVAC=@FIXPATH@ $(JAVAC_CMD)
JAVAH=@FIXPATH@ $(JAVAH_CMD)
JAVADOC=@FIXPATH@ $(JAVADOC_CMD)
JAR=@FIXPATH@ $(JAR_CMD)
JLINK = @FIXPATH@ $(JLINK_CMD) $(JAVA_TOOL_FLAGS_SMALL)
JMOD = @FIXPATH@ $(JMOD_CMD) $(JAVA_TOOL_FLAGS_SMALL)