[gentoo-dev] [PATCH] flag-o-matic.eclass: get rid of eutils in <EAPI-8, fix eclassdoc, make some funcs internal

[Andreas Sturmlechner]

qa-reports showing >7300 ebuilds with EAPI-7 using eutils.eclass, that can't be right.

- Restrict inherit eutils to <EAPI-8
- Drop bogus multilib.eclass (inherited by toolchain-funcs.eclass anyway)
- Several functions look like they should be internal
- Fix eclassdoc issues, add missing docu

See also:
https://qa-reports.gentoo.org/output/eapi-per-eclass/eutils.eclass/
https://github.com/gentoo/gentoo/pull/20207


diff --git a/eclass/flag-o-matic.eclass b/eclass/flag-o-matic.eclass
index 20ee39d98ba..35dc09f94de 100644
--- a/eclass/flag-o-matic.eclass
+++ b/eclass/flag-o-matic.eclass
@@ -1,4 +1,4 @@
-# Copyright 1999-2020 Gentoo Authors
+# Copyright 1999-2021 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: flag-o-matic.eclass
@@ -12,16 +12,37 @@
 if [[ -z ${_FLAG_O_MATIC_ECLASS} ]]; then
 _FLAG_O_MATIC_ECLASS=1
 
-inherit eutils toolchain-funcs multilib
+inherit toolchain-funcs
 
+case ${EAPI} in
+	[0-7]) inherit eutils ;;
+	*) ;;
+esac
+
+# @FUNCTION: all-flag-vars
+# @DESCRIPTION:
 # Return all the flag variables that our high level funcs operate on.
 all-flag-vars() {
 	echo {ADA,C,CPP,CXX,CCAS,F,FC,LD}FLAGS
 }
 
+# @FUNCTION: setup-allowed-flags
+# @INTERNAL
+# @DESCRIPTION:
 # {C,CPP,CXX,CCAS,F,FC,LD}FLAGS that we allow in strip-flags
 # Note: shell globs and character lists are allowed
 setup-allowed-flags() {
+	[[ ${EAPI} == [0-7] ]] ||
+		die "Internal function ${FUNCNAME} is not available in >=EAPI-8."
+	_setup-allowed-flags
+}
+
+# @FUNCTION: _setup-allowed-flags
+# @INTERNAL
+# @DESCRIPTION:
+# {C,CPP,CXX,CCAS,F,FC,LD}FLAGS that we allow in strip-flags
+# Note: shell globs and character lists are allowed
+_setup-allowed-flags() {
 	ALLOWED_FLAGS=(
 		-pipe -O '-O[12sg]' -mcpu -march -mtune
 		'-fstack-protector*' '-fsanitize*' '-fstack-check*' -fno-stack-check
@@ -87,7 +108,10 @@ setup-allowed-flags() {
 	)
 }
 
-# inverted filters for hardened compiler.  This is trying to unpick
+# @FUNCTION: _filter-hardened
+# @INTERNAL
+# @DESCRIPTION:
+# Inverted filters for hardened compiler.  This is trying to unpick
 # the hardened compiler defaults.
 _filter-hardened() {
 	local f
@@ -121,6 +145,9 @@ _filter-hardened() {
 	done
 }
 
+# @FUNCTION: _filter-var
+# @INTERNAL
+# @DESCRIPTION:
 # Remove occurrences of strings from variable given in $1
 # Strings removed are matched as globs, so for example
 # '-O*' would remove -O1, -O2 etc.
@@ -313,6 +340,11 @@ replace-cpu-flags() {
 	return 0
 }
 
+# @FUNCTION: _is_flagq
+# @USAGE: <variable> <flag>
+# @INTERNAL
+# @DESCRIPTION:
+# Returns shell true if <flag> is in a given <variable>, else returns shell false.
 _is_flagq() {
 	local x var="$1[*]"
 	for x in ${!var} ; do
@@ -405,7 +437,7 @@ strip-flags() {
 	local x y var
 
 	local ALLOWED_FLAGS
-	setup-allowed-flags
+	_setup-allowed-flags
 
 	set -f	# disable pathname expansion
 
@@ -438,7 +470,23 @@ strip-flags() {
 	return 0
 }
 
+# @FUNCTION: test-flag-PROG
+# @USAGE: <compiler> <flag>
+# @INTERNAL
+# @DESCRIPTION:
+# Returns shell true if <flag> is supported by given <compiler>, else returns shell false.
 test-flag-PROG() {
+	[[ ${EAPI} == [0-7] ]] ||
+		die "Internal function ${FUNCNAME} is not available in >=EAPI-8."
+	_test-flag-PROG
+}
+
+# @FUNCTION: _test-flag-PROG
+# @USAGE: <compiler> <flag>
+# @INTERNAL
+# @DESCRIPTION:
+# Returns shell true if <flag> is supported by given <compiler>, else returns shell false.
+_test-flag-PROG() {
 	local comp=$1
 	local lang=$2
 	shift 2
@@ -533,33 +581,49 @@ test-flag-PROG() {
 # @USAGE: <flag>
 # @DESCRIPTION:
 # Returns shell true if <flag> is supported by the C compiler, else returns shell false.
-test-flag-CC() { test-flag-PROG "CC" c "$@"; }
+test-flag-CC() { _test-flag-PROG "CC" c "$@"; }
 
 # @FUNCTION: test-flag-CXX
 # @USAGE: <flag>
 # @DESCRIPTION:
 # Returns shell true if <flag> is supported by the C++ compiler, else returns shell false.
-test-flag-CXX() { test-flag-PROG "CXX" c++ "$@"; }
+test-flag-CXX() { _test-flag-PROG "CXX" c++ "$@"; }
 
 # @FUNCTION: test-flag-F77
 # @USAGE: <flag>
 # @DESCRIPTION:
 # Returns shell true if <flag> is supported by the Fortran 77 compiler, else returns shell false.
-test-flag-F77() { test-flag-PROG "F77" f77 "$@"; }
+test-flag-F77() { _test-flag-PROG "F77" f77 "$@"; }
 
 # @FUNCTION: test-flag-FC
 # @USAGE: <flag>
 # @DESCRIPTION:
 # Returns shell true if <flag> is supported by the Fortran 90 compiler, else returns shell false.
-test-flag-FC() { test-flag-PROG "FC" f95 "$@"; }
+test-flag-FC() { _test-flag-PROG "FC" f95 "$@"; }
 
 # @FUNCTION: test-flag-CCLD
 # @USAGE: <flag>
 # @DESCRIPTION:
 # Returns shell true if <flag> is supported by the C compiler and linker, else returns shell false.
-test-flag-CCLD() { test-flag-PROG "CC" c+ld "$@"; }
+test-flag-CCLD() { _test-flag-PROG "CC" c+ld "$@"; }
 
+# @FUNCTION: test-flags-PROG
+# @USAGE: <compiler> <flag> [more flags...]
+# @INTERNAL
+# @DESCRIPTION:
+# Returns shell true if <flags> are supported by given <compiler>, else returns shell false.
 test-flags-PROG() {
+	[[ ${EAPI} == [0-7] ]] ||
+		die "Internal function ${FUNCNAME} is not available in >=EAPI-8."
+	_test-flags-PROG
+}
+
+# @FUNCTION: _test-flags-PROG
+# @USAGE: <compiler> <flag> [more flags...]
+# @INTERNAL
+# @DESCRIPTION:
+# Returns shell true if <flags> are supported by given <compiler>, else returns shell false.
+_test-flags-PROG() {
 	local comp=$1
 	local flags=()
 	local x
@@ -596,31 +660,31 @@ test-flags-PROG() {
 # @USAGE: <flags>
 # @DESCRIPTION:
 # Returns shell true if <flags> are supported by the C compiler, else returns shell false.
-test-flags-CC() { test-flags-PROG "CC" "$@"; }
+test-flags-CC() { _test-flags-PROG "CC" "$@"; }
 
 # @FUNCTION: test-flags-CXX
 # @USAGE: <flags>
 # @DESCRIPTION:
 # Returns shell true if <flags> are supported by the C++ compiler, else returns shell false.
-test-flags-CXX() { test-flags-PROG "CXX" "$@"; }
+test-flags-CXX() { _test-flags-PROG "CXX" "$@"; }
 
 # @FUNCTION: test-flags-F77
 # @USAGE: <flags>
 # @DESCRIPTION:
 # Returns shell true if <flags> are supported by the Fortran 77 compiler, else returns shell false.
-test-flags-F77() { test-flags-PROG "F77" "$@"; }
+test-flags-F77() { _test-flags-PROG "F77" "$@"; }
 
 # @FUNCTION: test-flags-FC
 # @USAGE: <flags>
 # @DESCRIPTION:
 # Returns shell true if <flags> are supported by the Fortran 90 compiler, else returns shell false.
-test-flags-FC() { test-flags-PROG "FC" "$@"; }
+test-flags-FC() { _test-flags-PROG "FC" "$@"; }
 
 # @FUNCTION: test-flags-CCLD
 # @USAGE: <flags>
 # @DESCRIPTION:
 # Returns shell true if <flags> are supported by the C compiler and default linker, else returns shell false.
-test-flags-CCLD() { test-flags-PROG "CCLD" "$@"; }
+test-flags-CCLD() { _test-flags-PROG "CCLD" "$@"; }
 
 # @FUNCTION: test-flags
 # @USAGE: <flags>