eclass: [QA] Revert multiple meaningless doc changes

Revert multiple meaningless eclass documentation changes, notably adding
a lot of placeholders and documenting implementation details.  These
changes were aimed at silencing (valid) documentation warnings without
actually providing valuable documentation to the end users.  While some
of these changes were beneficial, it would take a lot of effort to
review them all and the author is unwilling to fix his mistakes.

Signed-off-by: Michał Górny <mgorny@gentoo.org>

1 files changed, 0 insertions, 36 deletions

diff --git a/eclass/flag-o-matic.eclass b/eclass/flag-o-matic.eclass
index f7786725c5b9..20ee39d98bad 100644
--- a/eclass/flag-o-matic.eclass
+++ b/eclass/flag-o-matic.eclass
@@ -9,29 +9,18 @@
 # This eclass contains a suite of functions to help developers sanely
 # and safely manage toolchain flags in their builds.
 
-# @ECLASS-VARIABLE: _FLAG_O_MATIC_ECLASS
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
-
 if [[ -z ${_FLAG_O_MATIC_ECLASS} ]]; then
 _FLAG_O_MATIC_ECLASS=1
 
 inherit eutils toolchain-funcs multilib
 
-# @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
-# @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
@@ -98,12 +87,8 @@ setup-allowed-flags() {
 	)
 }
 
-# @FUNCTION: _filter-hardened
-# @INTERNAL
-# @DESCRIPTION:
 # inverted filters for hardened compiler.  This is trying to unpick
 # the hardened compiler defaults.
-
 _filter-hardened() {
 	local f
 	for f in "$@" ; do
@@ -136,13 +121,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.
-
 _filter-var() {
 	local f x var=$1 new=()
 	shift
@@ -161,7 +142,6 @@ _filter-var() {
 # @USAGE: <flags>
 # @DESCRIPTION:
 # Remove particular <flags> from {C,CPP,CXX,CCAS,F,FC,LD}FLAGS.  Accepts shell globs.
-
 filter-flags() {
 	_filter-hardened "$@"
 	local v
@@ -174,7 +154,6 @@ filter-flags() {
 # @FUNCTION: filter-lfs-flags
 # @DESCRIPTION:
 # Remove flags that enable Large File Support.
-
 filter-lfs-flags() {
 	[[ $# -ne 0 ]] && die "filter-lfs-flags takes no arguments"
 	# http://www.gnu.org/s/libc/manual/html_node/Feature-Test-Macros.html
@@ -188,7 +167,6 @@ filter-lfs-flags() {
 # @USAGE: <flags>
 # @DESCRIPTION:
 # Remove particular <flags> from LDFLAGS.  Accepts shell globs.
-
 filter-ldflags() {
 	_filter-var LDFLAGS "$@"
 	return 0
@@ -335,11 +313,6 @@ replace-cpu-flags() {
 	return 0
 }
 
-# @FUNCTION: _is_flagq
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
-
 _is_flagq() {
 	local x var="$1[*]"
 	for x in ${!var} ; do
@@ -465,10 +438,6 @@ strip-flags() {
 	return 0
 }
 
-# @FUNCTION: test-flag-PROG
-# @DESCRIPTION:
-# Please document me
-
 test-flag-PROG() {
 	local comp=$1
 	local lang=$2
@@ -588,13 +557,8 @@ test-flag-FC() { test-flag-PROG "FC" f95 "$@"; }
 # @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 "$@"; }
 
-# @FUNCTION: test-flags-PROG
-# @DESCRIPTION:
-# Please document me
-
 test-flags-PROG() {
 	local comp=$1
 	local flags=()