eclass/multilib-build: improve in-source doc for abi_arch_use

Signed-off-by: Gregory M. Tuner <gmt@be-evil.net>

1 files changed, 9 insertions, 6 deletions

diff --git a/eclass/multilib-build.eclass b/eclass/multilib-build.eclass
index 0dcc562..26f72e7 100644
--- a/eclass/multilib-build.eclass
+++ b/eclass/multilib-build.eclass
@@ -725,24 +725,27 @@ multilib_is_best_abi() {
 
 # @FUNCTION: abi_arch_use
 # @USAGE: <[!]pseudo-flag>
-# @RETURN: True (zero) if the pseudo-use-flag test is positive; analogous to use
+# @RETURN: True (zero) if the pseudo-use-flag test is positive, similar to use helper.
 # @DESCRIPTION:
 # Often pre-multilib-build ebuild and eclass code contain statements like:
 # @CODE
 # use foo && append-flags -funroll-loops
 # @CODE
+# where foo is an ARCH USE_EXPAND value such as "amd64".
 # When adapting such code to a multi-abi build environment based on
 # multilib-build.eclass, it is convenient to be able to quickly convert
 # such queries to instead check the currently activated ABI.  However,
-# there is a non-trivial mapping between the two!  This function acts
+# there is a non-trivial mapping between ARCHes and ABIs.  This function acts
 # syntactically like the "use" phase-helper; however, it only works on
 # ARCH USE_EXPAND values (those in ${PORTDIR}/profiles/arch.list).
 #
 # It operates only on whitelisted values of ${ABI}, so, if ${ABI} is unknown,
-# or if ${ARCH} is known to support a list of ABI's not equal to "${ARCH}",
-# and yet ${ABI} is not a known abi supported by ${ARCH}, this always returns
-# a nonzero (false) value (or a zero (true) value, when the pseudo-flag
-# argument is preceeded by an exclamation point).
+# or if ${ARCH} is known to have multilib support, but ${ABI} is not a
+# known abi for ${ARCH} (according to the hard-coded whitelist) then a
+# nonzero (false) value (or a zero (true) value, when
+# the pseudo-flag argument is preceeded by an exclamation point) would
+# be immediately returned, regardless of any underlying "truth" pertaining
+# to the multilib_build framework.
 abi_arch_use() {
 	debug-print-function ${FUNCNAME} "$@"