diff --git a/eclass/java-utils-2.eclass b/eclass/java-utils-2.eclass
index 058dabec9625a..54161946ea816 100644
--- a/eclass/java-utils-2.eclass
+++ b/eclass/java-utils-2.eclass
@@ -1609,7 +1609,8 @@ java-pkg_ensure-vm-version-ge() {
 # Parameters:
 # $@ - VM version to compare current VM to
 # @CODE
-# @RETURN: zero - current VM version is greater than checked version; non-zero - current VM version is not greater than checked version
+# @RETURN: zero - current VM version is greater than checked version
+# @RETURN: non-zero - current VM version is not greater than checked version
 java-pkg_is-vm-version-ge() {
 	debug-print-function ${FUNCNAME} $*
 
@@ -1629,14 +1630,14 @@ java-pkg_is-vm-version-ge() {
 	fi
 }
 
-java-pkg_set-current-vm() {
-	export GENTOO_VM=${1}
-}
-
 java-pkg_get-current-vm() {
 	echo ${GENTOO_VM}
 }
 
+# @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 $?
@@ -2310,7 +2311,9 @@ java-pkg_init() {
 	# TODO we will probably want to set JAVAC and JAVACFLAGS
 
 	# Do some QA checks
-	java-pkg_check-jikes
+	if has jikes ${IUSE}; then
+		java-pkg_announce-qa-violation "deprecated USE flag 'jikes' in IUSE"
+	fi
 
 	# Can't use unset here because Portage does not save the unset
 	# see https://bugs.gentoo.org/show_bug.cgi?id=189417#c11
@@ -2327,7 +2330,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
@@ -2348,9 +2351,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} $*
 
@@ -2812,20 +2813,6 @@ java-pkg_die() {
 	echo "and of course, the output of emerge --info =${P}" >&2
 }
 
-
-# TODO document
-# List jars in the source directory, ${S}
-java-pkg_jar-list() {
-	if [[ -n "${JAVA_PKG_DEBUG}" ]]; then
-		einfo "Linked Jars"
-		find "${S}" -type l -name '*.jar' -print0 | xargs -0 -r -n 500 ls -ald | sed -e "s,${WORKDIR},\${WORKDIR},"
-		einfo "Jars"
-		find "${S}" -type f -name '*.jar' -print0 | xargs -0 -r -n 500 ls -ald | sed -e "s,${WORKDIR},\${WORKDIR},"
-		einfo "Classes"
-		find "${S}" -type f -name '*.class' -print0 | xargs -0 -r -n 500 ls -ald | sed -e "s,${WORKDIR},\${WORKDIR},"
-	fi
-}
-
 # @FUNCTION: java-pkg_verify-classes
 # @INTERNAL
 # @DESCRIPTION:
@@ -2946,6 +2933,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]}
@@ -2955,6 +2948,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}
 
@@ -2963,28 +2962,26 @@ java-pkg_check-versioned-jar() {
 	fi
 }
 
-java-pkg_check-jikes() {
-	if has jikes ${IUSE}; then
-		java-pkg_announce-qa-violation "deprecated USE flag 'jikes' in IUSE"
-	fi
-}
-
+# @FUNCTION: java-pkg_announce-qa-violation
+# @INTERNAL
+# @USAGE: [--nodie] <msg>
+# @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
 		nodie="true"
 		shift
 	fi
-	echo "Java QA Notice: $@" >&2
-	increment-qa-violations
+	ewarn "Java QA Notice: $@"
 	[[ -z "${nodie}" ]] && is-java-strict && die "${@}"
 }
 
-increment-qa-violations() {
-	let "JAVA_PKG_QA_VIOLATIONS+=1"
-	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 $?