eclass/java-utils-2: Sync with Gentoo

It's from Gentoo commit c1a63f395cae95a5603715ef7d43f58253252a97.

sdk_container/src/third_party/portage-stable/eclass/java-utils-2.eclass

@@ -9,13 +9,12 @@
 # @SUPPORTED_EAPIS: 6 7 8
 # @BLURB: Base eclass for Java packages
 # @DESCRIPTION:
-# This eclass provides functionality which is used by java-pkg-2.eclass,
+# This eclass provides functionality which is used by java-pkg-2.eclass and
-# java-pkg-opt-2.eclass and java-ant-2 eclass, as well as from ebuilds.
+# java-pkg-opt-2.eclass as well as from ebuilds.
 #
 # This eclass should not be inherited this directly from an ebuild. Instead,
 # you should inherit java-pkg-2 for Java packages or java-pkg-opt-2 for packages
-# that have optional Java support. In addition you can inherit java-ant-2 for
+# that have optional Java support.
-# Ant-based packages.
 
 if [[ -z ${_JAVA_UTILS_2_ECLASS} ]] ; then
 _JAVA_UTILS_2_ECLASS=1
@@ -101,7 +100,7 @@ JAVA_PKG_ALLOW_VM_CHANGE=${JAVA_PKG_ALLOW_VM_CHANGE:="yes"}
 # @DEFAULT_UNSET
 # @DESCRIPTION:
 # Specify a non-standard Java source version for compilation (via javac -source
-# parameter or Ant equivalent via build.xml rewriting done by java-ant-2 eclass).
+# parameter).
 # Normally this is determined from the jdk version specified in DEPEND.
 # See java-pkg_get-source function below.
 #
@@ -204,9 +203,9 @@ JAVA_PKG_COMPILERS_CONF=${JAVA_PKG_COMPILERS_CONF:="/etc/java-config-2/build/com
 #
 # Useful for local testing.
 #
-# Use jikes and javac, in that order
+# Use <other compiler> and javac, in that order
 # @CODE
-#	JAVA_PKG_FORCE_COMPILER="jikes javac"
+#	JAVA_PKG_FORCE_COMPILER="<other compiler> javac"
 # @CODE
 
 # @ECLASS_VARIABLE: JAVA_PKG_FORCE_ANT_TASKS
@@ -1649,6 +1648,10 @@ java-pkg_set-current-vm() {
 	export GENTOO_VM=${1}
 }
 
+# @FUNCTION: java-pkg_current-vm-matches
+# @USAGE: <vm_string1> [<vm_string2> [<vm_string3>...]]
+# @RETURN: 0: the current vm matches any of the provided strings
+# @RETURN: 1: the current vm does not match any of the provided strings
 java-pkg_current-vm-matches() {
 	has $(java-pkg_get-current-vm) ${@}
 	return $?
@@ -2307,9 +2310,6 @@ java-pkg_init() {
 
 	# TODO we will probably want to set JAVAC and JAVACFLAGS
 
-	# Do some QA checks
-	java-pkg_check-jikes
-
 	# Can't use unset here because Portage does not save the unset
 	# see https://bugs.gentoo.org/show_bug.cgi?id=189417#c11
 
@@ -2325,7 +2325,7 @@ java-pkg_init() {
 	export ANT_RESPECT_JAVA_HOME=
 }
 
-# @FUNCTION: java-pkg-init-compiler_
+# @FUNCTION: java-pkg_init-compiler_
 # @INTERNAL
 # @DESCRIPTION:
 # This function attempts to figure out what compiler should be used. It does
@@ -2346,9 +2346,7 @@ java-pkg_init() {
 # If the user doesn't defined anything in JAVA_PKG_COMPILERS_CONF, or no
 # suitable compiler was found there, then the default is to use javac provided
 # by the current VM.
-#
+# @RETURN: name of the compiler to use
-#
-# @RETURN name of the compiler to use
 java-pkg_init-compiler_() {
 	debug-print-function ${FUNCNAME} $*
 
@@ -2950,6 +2948,12 @@ java-pkg_ensure-dep() {
 	fi
 }
 
+# @FUNCTION: java-pkg_check-phase
+# @INTERNAL
+# @USAGE: <phase_name>
+# @DESCRIPTION:
+# Checks whether the phase specified in $1 is the current active phase. If not,
+# a helpful QA message is displayed
 java-pkg_check-phase() {
 	local phase=${1}
 	local funcname=${FUNCNAME[1]}
@@ -2959,6 +2963,12 @@ java-pkg_check-phase() {
 	fi
 }
 
+# @FUNCTION: java-pkg_check-versioned-jar
+# @INTERNAL
+# @USAGE: <jar_filename>
+# @DESCRIPTION:
+# Checks whether the jar specified in $1 contains ${PV}. If it does, a helpful
+# QA message is displayed
 java-pkg_check-versioned-jar() {
 	local jar=${1}
 
@@ -2967,12 +2977,12 @@ java-pkg_check-versioned-jar() {
 	fi
 }
 
-java-pkg_check-jikes() {
+# @FUNCTION: java-pkg_announce-qa-violation
-	if has jikes ${IUSE}; then
+# @INTERNAL
-		java-pkg_announce-qa-violation "deprecated USE flag 'jikes' in IUSE"
+# @USAGE: [--nodie] <msg>
-	fi
+# @DESCRIPTION:
-}
+# Prints out the <msg> as a QA message. If ${JAVA_PKG_STRICT} is set, then die
-
+# is called. This can be overridden by providing --nodie
 java-pkg_announce-qa-violation() {
 	local nodie
 	if [[ ${1} == "--nodie" ]]; then
@@ -2989,6 +2999,10 @@ increment-qa-violations() {
 	export JAVA_PKG_QA_VIOLATIONS
 }
 
+# @FUNCTION: is-java-strict
+# @INTERNAL
+# @RETURN: 0: JAVA_PKG_STRICT is set
+# @RETURN: 1: JAVA_PKG_STRICT is not set
 is-java-strict() {
 	[[ -n ${JAVA_PKG_STRICT} ]]
 	return $?