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>

56 files changed, 71 insertions, 558 deletions

diff --git a/eclass/acct-group.eclass b/eclass/acct-group.eclass
index 18a40d7ad6f5..1d5d14290dad 100644
--- a/eclass/acct-group.eclass
+++ b/eclass/acct-group.eclass
@@ -31,11 +31,6 @@
 # - RDEPEND if it is needed at install time (e.g. you 'fowners' files
 #   in pkg_preinst) or run time.
 
-# @VARIABLE: _ACCT_GROUP_ECLASS
-# @INTERNAL
-# @DESCRIPTION:
-# If null set to 1
-
 if [[ -z ${_ACCT_GROUP_ECLASS} ]]; then
 _ACCT_GROUP_ECLASS=1
 
diff --git a/eclass/acct-user.eclass b/eclass/acct-user.eclass
index af5a4a923354..22b0038fbff7 100644
--- a/eclass/acct-user.eclass
+++ b/eclass/acct-user.eclass
@@ -39,11 +39,6 @@
 # - RDEPEND if it is needed at install time (e.g. you 'fowners' files
 #   in pkg_preinst) or run time.
 
-# @VARIABLE: _ACCT_USER_ECLASS
-# @INTERNAL
-# @DESCRIPTION:
-# If null set to 1
-
 if [[ -z ${_ACCT_USER_ECLASS} ]]; then
 _ACCT_USER_ECLASS=1
 
diff --git a/eclass/alternatives.eclass b/eclass/alternatives.eclass
index 108a55af8112..79f14d81b134 100644
--- a/eclass/alternatives.eclass
+++ b/eclass/alternatives.eclass
@@ -2,8 +2,6 @@
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: alternatives.eclass
-# @MAINTAINER:
-# maintainer-needed@gentoo.org
 # @AUTHOR:
 # Original author: Alastair Tse <liquidx@gentoo.org> (03 Oct 2003)
 # @BLURB: Creates symlink to the latest version of multiple slotted packages.
@@ -74,17 +72,14 @@ alternatives_auto_makesym() {
 	alternatives_makesym ${SYMLINK} ${ALT}
 }
 
-# @FUNCTION: alternatives_makesym
-# @USAGE: alternatives_makesym <resulting symlink> [alternative targets..]
-# @DESCRIPTION:
-# make sure it is in the prefix, allow it already to be in the prefix
-
 alternatives_makesym() {
 	has "${EAPI:-0}" 0 1 2 && ! use prefix && EPREFIX=
 	local ALTERNATIVES=""
 	local SYMLINK=""
 	local alt pref
 
+	# usage: alternatives_makesym <resulting symlink> [alternative targets..]
+	# make sure it is in the prefix, allow it already to be in the prefix
 	SYMLINK=${EPREFIX}/${1#${EPREFIX}}
 	# this trick removes the trailing / from ${ROOT}
 	pref=${ROOT%/}
@@ -129,7 +124,6 @@ alternatives_makesym() {
 # @FUNCTION: alernatives-pkg_postinst
 # @DESCRIPTION:
 # The alternatives pkg_postinst, this function will be exported
-
 alternatives_pkg_postinst() {
 	if [ -n "${ALTERNATIVES}" -a -n "${SOURCE}" ]; then
 		alternatives_makesym ${SOURCE} ${ALTERNATIVES}
@@ -139,7 +133,6 @@ alternatives_pkg_postinst() {
 # @FUNCTION: alternatives_pkg_postrm
 # @DESCRIPTION:
 # The alternatives pkg_postrm, this function will be exported
-
 alternatives_pkg_postrm() {
 	if [ -n "${ALTERNATIVES}" -a -n "${SOURCE}" ]; then
 		alternatives_makesym ${SOURCE} ${ALTERNATIVES}
diff --git a/eclass/ant-tasks.eclass b/eclass/ant-tasks.eclass
index a96222f8ff50..42f801a84d70 100644
--- a/eclass/ant-tasks.eclass
+++ b/eclass/ant-tasks.eclass
@@ -1,4 +1,4 @@
-# Copyright 2007-2019 Gentoo Authors
+# Copyright 2007-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: ant-tasks.eclass
@@ -66,7 +66,6 @@ ANT_TASK_DEPNAME=${ANT_TASK_DEPNAME-${ANT_TASK_NAME}}
 
 # @VARIABLE: ANT_TASK_PV
 # @INTERNAL
-# @DESCRIPTION:
 # Version of ant-core this task is intended to register and thus load with.
 ANT_TASK_PV="${PV}"
 
diff --git a/eclass/apache-2.eclass b/eclass/apache-2.eclass
index ded2b6696aa7..ccfe482f528e 100644
--- a/eclass/apache-2.eclass
+++ b/eclass/apache-2.eclass
@@ -1,4 +1,4 @@
-# Copyright 1999-2019 Gentoo Authors
+# Copyright 1999-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: apache-2.eclass
@@ -87,12 +87,7 @@ SRC_URI="mirror://apache/httpd/httpd-${PV}.tar.bz2
 # This variable needs to be set in the ebuild and contains a list of available
 # built-in modules
 
-# @VARIABLE: IUSE_MPMS
-# @DESCRIPTION:
-# Combine IUSE_MPMS_FORK and IUSE_MPMS_THREAD
-
 IUSE_MPMS="${IUSE_MPMS_FORK} ${IUSE_MPMS_THREAD}"
-
 IUSE="${IUSE} debug doc gdbm ldap libressl selinux ssl static suexec threads"
 
 for module in ${IUSE_MODULES} ; do
diff --git a/eclass/apache-module.eclass b/eclass/apache-module.eclass
index 05372bcd426e..e192a7454277 100644
--- a/eclass/apache-module.eclass
+++ b/eclass/apache-module.eclass
@@ -95,11 +95,7 @@ inherit depend.apache
 # INTERNAL FUNCTIONS
 # ==============================================================================
 
-# @FUNCTION: apache_cd_dir
-# @INTERNAL
-# @DESCRIPTION:
 # Internal function to construct the default ${APXS2_S} path if required.
-
 apache_cd_dir() {
 	debug-print-function $FUNCNAME $*
 
@@ -117,11 +113,7 @@ apache_cd_dir() {
 	echo "${CD_DIR}"
 }
 
-# @FUNCTION: apache_mod_file
-# @INTERNAL
-# @DESCRIPTION:
 # Internal function to construct the default ${APACHE2_MOD_FILE} if required.
-
 apache_mod_file() {
 	debug-print-function $FUNCNAME $*
 
@@ -131,13 +123,9 @@ apache_mod_file() {
 	echo "${MOD_FILE}"
 }
 
-# @FUNCTION: apache_doc_magic
-# @INTERNAL
-# @DESCRIPTION:
 # Internal function for picking out html files from ${DOCFILES}. It takes an
 # optional first argument `html'; if the first argument is equals `html', only
 # html files are returned, otherwise normal (non-html) docs are returned.
-
 apache_doc_magic() {
 	debug-print-function $FUNCNAME $*
 
diff --git a/eclass/aspell-dict-r1.eclass b/eclass/aspell-dict-r1.eclass
index 14e2b0b6344c..b07af61fdf1e 100644
--- a/eclass/aspell-dict-r1.eclass
+++ b/eclass/aspell-dict-r1.eclass
@@ -42,11 +42,6 @@ esac
 
 EXPORT_FUNCTIONS src_configure src_install
 
-# @VARIABLE: _ASPELL_DICT_R1
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
-
 if [[ ! ${_ASPELL_DICT_R1} ]]; then
 
 # aspell packages have an idiosyncratic versioning scheme, that is
diff --git a/eclass/autotools-utils.eclass b/eclass/autotools-utils.eclass
index 13d2f653a972..3fcaa79f80ab 100644
--- a/eclass/autotools-utils.eclass
+++ b/eclass/autotools-utils.eclass
@@ -113,11 +113,6 @@ esac
 # Note that dependencies are added for autoconf, automake and libtool only.
 # If your package needs one of the external tools listed above, you need to add
 # appropriate packages to DEPEND yourself.
-
-# @VARIABLE: AUTOTOOLS_AUTO_DEPEND
-# @DESCRIPTION:
-# Please document me
-
 [[ ${AUTOTOOLS_AUTORECONF} ]] || : ${AUTOTOOLS_AUTO_DEPEND:=no}
 
 # eutils for eqawarn, path_exists
@@ -197,12 +192,6 @@ EXPORT_FUNCTIONS src_prepare src_configure src_compile src_install src_test
 # cases only.
 
 # Determine using IN or OUT source build
-
-# @FUNCTION: _check_build_dir
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
-
 _check_build_dir() {
 	: ${ECONF_SOURCE:=${S}}
 	# Respect both the old variable and the new one, depending
diff --git a/eclass/autotools.eclass b/eclass/autotools.eclass
index 12c8e899d19f..d7ce23bfdf35 100644
--- a/eclass/autotools.eclass
+++ b/eclass/autotools.eclass
@@ -23,11 +23,6 @@ if [[ ${__AUTOTOOLS_AUTO_DEPEND+set} == "set" ]] ; then
 	fi
 fi
 
-# @ECLASS-VARIABLE: _AUTOTOOLS_ECLASS
-# @INTERNAL
-# @DESCRIPTION:
-# Please document
-
 if [[ -z ${_AUTOTOOLS_ECLASS} ]]; then
 _AUTOTOOLS_ECLASS=1
 
@@ -104,11 +99,6 @@ if [[ -n ${WANT_AUTOCONF} ]] ; then
 	export WANT_AUTOCONF
 fi
 
-# @ECLASS-VARIABLE: _libtool_atom
-# @INTERNAL
-# @DESCRIPTION:
-# Set libtool ${P}
-
 _libtool_atom=">=sys-devel/libtool-2.4"
 if [[ -n ${WANT_LIBTOOL} ]] ; then
 	case ${WANT_LIBTOOL} in
@@ -119,10 +109,6 @@ if [[ -n ${WANT_LIBTOOL} ]] ; then
 	export WANT_LIBTOOL
 fi
 
-# @ECLASS-VARIABLE: AUTOTOOLS_DEPEND
-# @DESCRIPTION:
-# Set DEPEND
-
 AUTOTOOLS_DEPEND="${_automake_atom}
 	${_autoconf_atom}
 	${_libtool_atom}"
@@ -133,7 +119,6 @@ RDEPEND=""
 # Set to 'no' to disable automatically adding to DEPEND.  This lets
 # ebuilds form conditional depends by using ${AUTOTOOLS_DEPEND} in
 # their own DEPEND string.
-
 : ${AUTOTOOLS_AUTO_DEPEND:=yes}
 if [[ ${AUTOTOOLS_AUTO_DEPEND} != "no" ]] ; then
 	case ${EAPI:-0} in
@@ -141,12 +126,6 @@ if [[ ${AUTOTOOLS_AUTO_DEPEND} != "no" ]] ; then
 		7) BDEPEND=${AUTOTOOLS_DEPEND} ;;
 	esac
 fi
-
-# @ECLASS-VARIABLE: __AUTOTOOLS_AUTO_DEPEND
-# @INTERNAL
-# @DESCRIPTION:
-# Set internal variable
-
 __AUTOTOOLS_AUTO_DEPEND=${AUTOTOOLS_AUTO_DEPEND} # See top of eclass
 
 unset _automake_atom _autoconf_atom
@@ -272,7 +251,6 @@ eautoreconf() {
 # @FUNCTION: _at_uses_pkg
 # @USAGE: <macros>
 # @INTERNAL
-# @DESCRIPTION:
 # See if the specified macros are enabled.
 _at_uses_pkg() {
 	if [[ -n $(autotools_check_macro "$@") ]] ; then
@@ -287,68 +265,14 @@ _at_uses_pkg() {
 		egrep -q "${args[@]}" configure.??
 	fi
 }
-
-# @FUNCTION: _at_uses_autoheader
-# @INTERNAL
-# @DESCRIPTION:
-# Call another function
-
 _at_uses_autoheader()  { _at_uses_pkg A{C,M}_CONFIG_HEADER{S,}; }
-
-# @FUNCTION: _at_uses_automake
-# @INTERNAL
-# @DESCRIPTION:
-# Call another function
-
 _at_uses_automake()    { _at_uses_pkg AM_INIT_AUTOMAKE; }
-
-# @FUNCTION: _at_uses_gettext
-# @INTERNAL
-# @DESCRIPTION:
-# Call another function
-
 _at_uses_gettext()     { _at_uses_pkg AM_GNU_GETTEXT_{,REQUIRE_}VERSION; }
-
-# @FUNCTION: _at_uses_glibgettext
-# @INTERNAL
-# @DESCRIPTION:
-# Call another function
-
 _at_uses_glibgettext() { _at_uses_pkg AM_GLIB_GNU_GETTEXT; }
-
-# @FUNCTION: _at_uses_intltool
-# @INTERNAL
-# @DESCRIPTION:
-# Call another function
-
 _at_uses_intltool()    { _at_uses_pkg {AC,IT}_PROG_INTLTOOL; }
-
-# @FUNCTION: _at_uses_gtkdoc
-# @INTERNAL
-# @DESCRIPTION:
-# Call another function
-
 _at_uses_gtkdoc()      { _at_uses_pkg GTK_DOC_CHECK; }
-
-# @FUNCTION: _at_uses_gnomedoc
-# @INTERNAL
-# @DESCRIPTION:
-# Call another function
-
 _at_uses_gnomedoc()    { _at_uses_pkg GNOME_DOC_INIT; }
-
-# @FUNCTION: _at_uses_libtool
-# @INTERNAL
-# @DESCRIPTION:
-# Call another function
-
 _at_uses_libtool()     { _at_uses_pkg A{C,M}_PROG_LIBTOOL LT_INIT; }
-
-# @FUNCTION: _at_uses_libltdl
-# @INTERNAL
-# @DESCRIPTION:
-# Call another function
-
 _at_uses_libltdl()     { _at_uses_pkg LT_CONFIG_LTDL_DIR; }
 
 # @FUNCTION: eaclocal_amflags
@@ -367,10 +291,10 @@ eaclocal_amflags() {
 		autotools_env_setup
 		aclocal_opts=$(sed -n \
 			"/^ACLOCAL_AMFLAGS[[:space:]]*=/{ \
-			# match the first line
-			s:[^=]*=::p; \
-			# then gobble up all escaped lines
-			: nextline /\\\\$/{ n; p; b nextline; } \
+			  # match the first line
+			  s:[^=]*=::p; \
+			  # then gobble up all escaped lines
+			  : nextline /\\\\$/{ n; p; b nextline; } \
 			}" ${amflags_file})
 		eval aclocal_opts=\""${aclocal_opts}"\"
 		break
@@ -626,11 +550,10 @@ autotools_run_tool() {
 	fi
 }
 
-# @ECLASS-VARIABLE: ALL_AUTOTOOLS_MACROS
-# @DESCRIPTION:
+# Internal function to check for support
+
 # Keep a list of all the macros we might use so that we only
 # have to run the trace code once.  Order doesn't matter.
-
 ALL_AUTOTOOLS_MACROS=(
 	A{C,M}_PROG_LIBTOOL LT_INIT LT_CONFIG_LTDL_DIR
 	A{C,M}_CONFIG_HEADER{S,}
@@ -643,11 +566,6 @@ ALL_AUTOTOOLS_MACROS=(
 	GTK_DOC_CHECK
 	GNOME_DOC_INIT
 )
-
-# @FUNCTION: autotools_check_macro
-# @DESCRIPTION:
-# Check the macros
-
 autotools_check_macro() {
 	[[ -f configure.ac || -f configure.in ]] || return 0
 
@@ -673,7 +591,6 @@ autotools_check_macro() {
 # @INTERNAL
 # @DESCRIPTION:
 # Look for a macro and extract its value.
-
 autotools_check_macro_val() {
 	local macro scan_out
 
@@ -689,11 +606,6 @@ autotools_check_macro_val() {
 	return 0
 }
 
-# @FUNCTION: _autotools_m4dir_include
-# @INTERNAL
-# @DESCRIPTION:
-# m4dir include stuff
-
 _autotools_m4dir_include() {
 	local x include_opts flag
 
@@ -715,17 +627,7 @@ _autotools_m4dir_include() {
 
 	echo ${include_opts}
 }
-
-# @FUNCTION: autotools_m4dir_include
-# @DESCRIPTION:
-# Call another function
-
 autotools_m4dir_include()    { _autotools_m4dir_include ${AT_M4DIR} ; }
-
-# @FUNCTION: autotools_m4sysdir_include
-# @DESCRIPTION:
-# m4sysdir include stuff
-
 autotools_m4sysdir_include() {
 	# First try to use the paths the system integrator has set up.
 	local paths=( $(eval echo ${AT_SYS_M4DIR}) )
diff --git a/eclass/base.eclass b/eclass/base.eclass
index 4682890b3dc3..0f9a2e576b78 100644
--- a/eclass/base.eclass
+++ b/eclass/base.eclass
@@ -28,22 +28,12 @@
 # @DESCRIPTION:
 # The base eclass defines some default functions and variables.
 
-# @VARIABLE: _BASE_ECLASS
-# @INTERNAL
-# @DESCRIPTION:
-# If null set to 1
-
 if [[ -z ${_BASE_ECLASS} ]]; then
 _BASE_ECLASS=1
 
 inherit eutils
 
-# @VARIABLE: BASE_EXPF
-# @DESCRIPTION:
-# Please document me
-
 BASE_EXPF="src_unpack src_compile src_install"
-
 case "${EAPI:-0}" in
 	0|1) ;;
 	2|3|4|5) BASE_EXPF+=" src_prepare src_configure" ;;
diff --git a/eclass/bash-completion-r1.eclass b/eclass/bash-completion-r1.eclass
index b5c7d2854f75..70d40a25969e 100644
--- a/eclass/bash-completion-r1.eclass
+++ b/eclass/bash-completion-r1.eclass
@@ -1,4 +1,4 @@
-# Copyright 1999-2019 Gentoo Authors
+# Copyright 1999-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: bash-completion-r1.eclass
@@ -61,11 +61,10 @@ _bash-completion-r1_get_bashcompdir() {
 	_bash-completion-r1_get_bashdir completionsdir /usr/share/bash-completion/completions
 }
 
-# @FUNCTION: _bash-completion-r1_get_bashhelpersdir
+# @FUNCTION: _bash-completion-r1_get_helpersdir
 # @INTERNAL
 # @DESCRIPTION:
 # Get unprefixed bash-completion helpers directory.
-
 _bash-completion-r1_get_bashhelpersdir() {
 	debug-print-function ${FUNCNAME} "${@}"
 
diff --git a/eclass/bazel.eclass b/eclass/bazel.eclass
index 493e2d4593d6..854b740db4f2 100644
--- a/eclass/bazel.eclass
+++ b/eclass/bazel.eclass
@@ -24,11 +24,6 @@ case "${EAPI:-0}" in
 		;;
 esac
 
-# @VARIABLE: _BAZEL_ECLASS
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
-
 if [[ ! ${_BAZEL_ECLASS} ]]; then
 
 inherit multiprocessing toolchain-funcs
diff --git a/eclass/cargo.eclass b/eclass/cargo.eclass
index d1e968b4e9ce..7f7a681f6f52 100644
--- a/eclass/cargo.eclass
+++ b/eclass/cargo.eclass
@@ -9,18 +9,10 @@
 # @SUPPORTED_EAPIS: 6 7
 # @BLURB: common functions and variables for cargo builds
 
-# @VARIABLE: _CARGO_ECLASS
-# @INTERNAL
-# @DESCRIPTION:
-# If null set to 1
-
 if [[ -z ${_CARGO_ECLASS} ]]; then
 _CARGO_ECLASS=1
 
-# @VARIABLE: RUST_DEPEND
-# @DESCRIPTION:
 # we need this for 'cargo vendor' subcommand and net.offline config knob
-
 RUST_DEPEND=">=virtual/rust-1.37.0"
 
 case "${EAPI:-0}" in
@@ -43,16 +35,7 @@ fi
 
 IUSE="${IUSE} debug"
 
-# @VARIABLE: ECARGO_HOME
-# @DESCRIPTION:
-# Adjust the working directory
-
 ECARGO_HOME="${WORKDIR}/cargo_home"
-
-# @VARIABLE: ECARGO_VENDOR
-# @DESCRIPTION:
-# Vendorize the working directory
-
 ECARGO_VENDOR="${ECARGO_HOME}/gentoo"
 
 # @ECLASS-VARIABLE: CARGO_OPTIONAL
diff --git a/eclass/cdrom.eclass b/eclass/cdrom.eclass
index 4481eaa1dd9b..4bbe6aa31759 100644
--- a/eclass/cdrom.eclass
+++ b/eclass/cdrom.eclass
@@ -14,11 +14,6 @@
 # eclass will require RESTRICT="bindist" but the point still stands.
 # The functions are generally called in src_unpack.
 
-# @VARIABLE: _CDROM_ECLASS
-# @INTERNAL
-# @DESCRIPTION:
-# If null set to 1
-
 if [[ -z ${_CDROM_ECLASS} ]]; then
 _CDROM_ECLASS=1
 
diff --git a/eclass/check-reqs.eclass b/eclass/check-reqs.eclass
index e512c1bb23a0..a45cbd15fee7 100644
--- a/eclass/check-reqs.eclass
+++ b/eclass/check-reqs.eclass
@@ -38,11 +38,6 @@
 # These checks should probably mostly work on non-Linux, and they should
 # probably degrade gracefully if they don't. Probably.
 
-# @VARIABLE: _CHECK_REQS_ECLASS_
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
-
 if [[ ! ${_CHECK_REQS_ECLASS_} ]]; then
 
 # @ECLASS-VARIABLE: CHECKREQS_MEMORY
@@ -72,8 +67,6 @@ esac
 
 EXPORT_FUNCTIONS pkg_pretend pkg_setup
 
-# @FUNCTION: check_reqs
-# @DESCRIPTION:
 # Obsolete function executing all the checks and printing out results
 check_reqs() {
 	eerror "Package calling old ${FUNCNAME} function."
@@ -357,8 +350,8 @@ check-reqs_unsatisfied() {
 	${msg} "There is NOT at least ${sizeunit} ${location}"
 
 	# @ECLASS-VARIABLE: CHECKREQS_FAILED
-	# @INTERNAL
 	# @DESCRIPTION:
+	# @INTERNAL
 	# If set the checks failed and eclass should abort the build.
 	# Internal, do not set yourself.
 	CHECKREQS_FAILED="true"
diff --git a/eclass/chromium-2.eclass b/eclass/chromium-2.eclass
index d8225f983e2f..b3d63f302d05 100644
--- a/eclass/chromium-2.eclass
+++ b/eclass/chromium-2.eclass
@@ -43,11 +43,6 @@ chromium_suid_sandbox_check_kernel_config() {
 # @DESCRIPTION:
 # List of language packs available for this package.
 
-# @FUNCTION: _chromium_set_l10n_IUSE
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
-
 _chromium_set_l10n_IUSE() {
 	[[ ${EAPI:-0} == 0 ]] && die "EAPI=${EAPI} is not supported"
 
@@ -105,10 +100,6 @@ chromium_remove_language_paks() {
 	done
 }
 
-# @FUNCTION: chromium_pkg_die
-# @DESCRIPTION:
-# Various reasons to die
-
 chromium_pkg_die() {
 	if [[ "${EBUILD_PHASE}" != "compile" ]]; then
 		return
diff --git a/eclass/cmake.eclass b/eclass/cmake.eclass
index 384556fd7d14..62fa02715700 100644
--- a/eclass/cmake.eclass
+++ b/eclass/cmake.eclass
@@ -17,11 +17,6 @@
 # out-of-source builds (default), in-source builds and an implementation of the
 # well-known use_enable function for CMake.
 
-# @VARIABLE: _CMAKE_ECLASS
-# @INTERNAL
-# @DESCRIPTION:
-# If null set to 1
-
 if [[ -z ${_CMAKE_ECLASS} ]]; then
 _CMAKE_ECLASS=1
 
@@ -140,10 +135,7 @@ _cmake_banned_func() {
 	die "${FUNCNAME[1]} is banned. use -D$1<related_CMake_variable>=\"\$(usex $2)\" instead"
 }
 
-# @FUNCTION: _cmake_check_build_dir
-# @DESCRIPTION:
 # Determine using IN or OUT source build
-
 _cmake_check_build_dir() {
 	: ${CMAKE_USE_DIR:=${S}}
 	if [[ -n ${CMAKE_IN_SOURCE_BUILD} ]]; then
@@ -276,12 +268,8 @@ cmake-utils_use() { _cmake_banned_func "" "$@" ; }
 # Banned. Use -DNOFOO=$(usex !foo) instead.
 cmake-utils_useno() { _cmake_banned_func "" "$@" ; }
 
-# @FUNCTION: _cmake_modify-cmakelists
-# @INTERNAL
-# @DESCRIPTION:
 # Internal function for modifying hardcoded definitions.
 # Removes dangerous definitions that override Gentoo settings.
-
 _cmake_modify-cmakelists() {
 	debug-print-function ${FUNCNAME} "$@"
 
diff --git a/eclass/cuda.eclass b/eclass/cuda.eclass
index cfc42a859495..b1da77c69dda 100644
--- a/eclass/cuda.eclass
+++ b/eclass/cuda.eclass
@@ -25,11 +25,6 @@ esac
 # @EXAMPLE:
 # inherit cuda
 
-# @VARIABLE: _CUDA_ECLASS
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
-
 if [[ -z ${_CUDA_ECLASS} ]]; then
 
 inherit flag-o-matic toolchain-funcs
diff --git a/eclass/cvs.eclass b/eclass/cvs.eclass
index f3d0d4f6b452..dd3cbe135a39 100644
--- a/eclass/cvs.eclass
+++ b/eclass/cvs.eclass
@@ -1,4 +1,4 @@
-# Copyright 1999-2019 Gentoo Authors
+# Copyright 1999-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: cvs.eclass
@@ -13,11 +13,6 @@
 # cvs_src_unpack. If you find that you need to call the cvs_* functions
 # directly, I'd be interested to hear about it.
 
-# @ECLASS-VARIABLE: _CVS_ECLASS
-# @INTERNAL
-# @DESCRIPTION:
-# Please document
-
 if [[ -z ${_CVS_ECLASS} ]]; then
 _CVS_ECLASS=1
 
@@ -200,11 +195,6 @@ case ${EAPI:-0} in
 esac
 
 # called from cvs_src_unpack
-
-# @FUNCTION: cvs_fetch
-# @DESCRIPTION:
-# Fetch CVS repo
-
 cvs_fetch() {
 	# Make these options local variables so that the global values are
 	# not affected by modifications in this function.
diff --git a/eclass/db-use.eclass b/eclass/db-use.eclass
index de257a9ae23b..7633425bac3b 100644
--- a/eclass/db-use.eclass
+++ b/eclass/db-use.eclass
@@ -1,15 +1,8 @@
 # Copyright 1999-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
-
-# @ECLASS: db-use.eclass
-# @MAINTAINER:
-# maintainer-needed@gentoo.org
-# @AUTHOR:
-# Paul de Vrieze <pauldv@gentoo.org>
-# @SUPPORTED_EAPIS: 0 1 2 3 4 5 6 7
-# @BLURB: functions that aid the use of sys-libs/db
-# @DESCRIPTION:
-# functions that aid in the use of sys-libs/db
+# This is a common location for functions that aid the use of sys-libs/db
+#
+# Bugs: maintainer-needed@gentoo.org
 
 # multilib is used for get_libname in all EAPI
 case "${EAPI:-0}" in
@@ -17,10 +10,7 @@ case "${EAPI:-0}" in
 	*) inherit multilib ;;
 esac
 
-# @FUNCTION: db_ver_to_slot
-# @USAGE: <version>
-# @DESCRIPTION:
-# Convert a version to a db slot
+#Convert a version to a db slot
 db_ver_to_slot() {
 	if [ $# -ne 1 ]; then
 		eerror "Function db_ver_to_slot needs one argument" >&2
@@ -38,10 +28,7 @@ db_ver_to_slot() {
 	echo -n "$1"
 }
 
-# @FUNCTION: db_findver
-# @USAGE: <atom>
-# @DESCRIPTION:
-# Find the version that corresponds to the given atom
+#Find the version that correspond to the given atom
 db_findver() {
 	has "${EAPI:-0}" 0 1 2 && ! use prefix && EPREFIX=
 	if [ $# -ne 1 ]; then
@@ -65,9 +52,6 @@ db_findver() {
 	fi
 }
 
-# @FUNCTION: db_includedir
-# @USAGE: <version>
-# @DESCRIPTION:
 # Get the include dir for berkeley db.
 # This function has two modes. Without any arguments it will give the best
 # version available. With arguments that form the versions of db packages
@@ -87,7 +71,7 @@ db_includedir() {
 			return 1
 		fi
 	else
-		# arguments given
+		#arguments given
 		for x in $@
 		do
 			if VER=$(db_findver "=sys-libs/db-${x}*") &&
@@ -101,9 +85,7 @@ db_includedir() {
 	fi
 }
 
-# @FUNCTION: db_libname
-# @USAGE: <version>
-# @DESCRIPTION:
+
 # Get the library name for berkeley db. Something like "db-4.2" will be the
 # outcome. This function has two modes. Without any arguments it will give
 # the best version available. With arguments that form the versions of db
@@ -121,7 +103,7 @@ db_libname() {
 			return 1
 		fi
 	else
-		# arguments given
+		#arguments given
 		for x in $@
 		do
 			if VER=$(db_findver "=sys-libs/db-${x}*"); then
diff --git a/eclass/db.eclass b/eclass/db.eclass
index 8e20c249476a..9a246d18979a 100644
--- a/eclass/db.eclass
+++ b/eclass/db.eclass
@@ -1,4 +1,4 @@
-# Copyright 1999-2019 Gentoo Authors
+# Copyright 1999-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: db.eclass
@@ -16,10 +16,6 @@ DEPEND="test? ( >=dev-lang/tcl-8.4 )"
 
 RDEPEND=""
 
-# @FUNCTION: db_fix_so
-# @DESCRIPTION:
-# Please document me
-
 db_fix_so() {
 	has "${EAPI:-0}" 0 1 2 && ! use prefix && EROOT="${ROOT}"
 	LIB="${EROOT}/usr/$(get_libdir)"
@@ -73,10 +69,6 @@ db_fix_so() {
 	fi
 }
 
-# @FUNCTION: db_src_install_doc
-# @DESCRIPTION:
-# Please document me
-
 db_src_install_doc() {
 	has "${EAPI:-0}" 0 1 2 && ! use prefix && ED="${D}"
 	# not everybody wants this wad of documentation as it is primarily API docs
@@ -91,10 +83,6 @@ db_src_install_doc() {
 	db_src_install_examples
 }
 
-# @FUNCTION: db_src_install_examples
-# @DESCRIPTION:
-# Please document me
-
 db_src_install_examples() {
 	has "${EAPI:-0}" 0 1 2 && ! use prefix && ED="${D}"
 	if use examples ; then
@@ -114,10 +102,6 @@ db_src_install_examples() {
 	fi
 }
 
-# @FUNCTION: db_src_install_usrbinslot
-# @DESCRIPTION:
-# Please document me
-
 db_src_install_usrbinslot() {
 	has "${EAPI:-0}" 0 1 2 && ! use prefix && ED="${D}"
 	# slot all program names to avoid overwriting
@@ -132,10 +116,6 @@ db_src_install_usrbinslot() {
 	done
 }
 
-# @FUNCTION: db_src_install_headerslot
-# @DESCRIPTION:
-# Please document me
-
 db_src_install_headerslot() {
 	has "${EAPI:-0}" 0 1 2 && ! use prefix && ED="${D}"
 	# install all headers in a slotted location
@@ -143,10 +123,6 @@ db_src_install_headerslot() {
 	mv "${ED}"/usr/include/*.h "${ED}"/usr/include/db${SLOT}/ || die
 }
 
-# @FUNCTION: db_src_install_usrlibcleanup
-# @DESCRIPTION:
-# Please document me
-
 db_src_install_usrlibcleanup() {
 	has "${EAPI:-0}" 0 1 2 && ! use prefix && ED="${D}"
 	LIB="${ED}/usr/$(get_libdir)"
diff --git a/eclass/depend.apache.eclass b/eclass/depend.apache.eclass
index 46bf93461bc0..5aa552542680 100644
--- a/eclass/depend.apache.eclass
+++ b/eclass/depend.apache.eclass
@@ -127,11 +127,6 @@ APACHE2_4_DEPEND="=www-servers/apache-2.4*"
 # INTERNAL FUNCTIONS
 # ==============================================================================
 
-# @FUNCTION: _init_apache2
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
-
 _init_apache2() {
 	debug-print-function $FUNCNAME $*
 
@@ -153,21 +148,11 @@ _init_apache2() {
 	esac
 }
 
-# @FUNCTION: _init_apache2_late
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
-
 _init_apache2_late() {
 	APACHE_BASEDIR="/usr/$(get_libdir)/apache2"
 	APACHE_MODULESDIR="${APACHE_BASEDIR}/modules"
 }
 
-# @FUNCTION: _init_no_apache
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
-
 _init_no_apache() {
 	debug-print-function $FUNCNAME $*
 	APACHE_VERSION="0"
diff --git a/eclass/desktop.eclass b/eclass/desktop.eclass
index 20b4d1797305..7d5c0f0f9a26 100644
--- a/eclass/desktop.eclass
+++ b/eclass/desktop.eclass
@@ -6,11 +6,6 @@
 # base-system@gentoo.org
 # @BLURB: support for desktop files, menus, and icons
 
-# @VARIABLE: _DESKTOP_ECLASS
-# @INTERNAL
-# @DESCRIPTION:
-# If null set to 1
-
 if [[ -z ${_DESKTOP_ECLASS} ]]; then
 _DESKTOP_ECLASS=1
 
diff --git a/eclass/distutils-r1.eclass b/eclass/distutils-r1.eclass
index d626d816369c..5ffc91be479c 100644
--- a/eclass/distutils-r1.eclass
+++ b/eclass/distutils-r1.eclass
@@ -95,11 +95,6 @@ esac
 # It needs to be set before the inherit line.
 : ${DISTUTILS_USE_SETUPTOOLS:=bdepend}
 
-# @VARIABLE: _DISTUTILS_R1
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
-
 if [[ ! ${_DISTUTILS_R1} ]]; then
 
 [[ ${EAPI} == [456] ]] && inherit eutils
@@ -1198,66 +1193,34 @@ distutils-r1_src_install() {
 
 # -- distutils.eclass functions --
 
-# @FUNCTION: distutils_get_intermediate_installation_image
-# @INTERNAL
-# @DESCRIPTION:
-# Die and warn when function from previous distutils is called
 distutils_get_intermediate_installation_image() {
 	die "${FUNCNAME}() is invalid for distutils-r1"
 }
 
-# @FUNCTION: distutils_src_unpack
-# @INTERNAL
-# @DESCRIPTION:
-# Die and warn when function from previous distutils is called
 distutils_src_unpack() {
 	die "${FUNCNAME}() is invalid for distutils-r1, and you don't want it in EAPI ${EAPI} anyway"
 }
 
-# @FUNCTION: distutils_src_prepare
-# @INTERNAL
-# @DESCRIPTION:
-# Die and warn when function from previous distutils is called
 distutils_src_prepare() {
 	die "${FUNCNAME}() is invalid for distutils-r1, you probably want: ${FUNCNAME/_/-r1_}"
 }
 
-# @FUNCTION: distutils_src_compile
-# @INTERNAL
-# @DESCRIPTION:
-# Die and warn when function from previous distutils is called
 distutils_src_compile() {
 	die "${FUNCNAME}() is invalid for distutils-r1, you probably want: ${FUNCNAME/_/-r1_}"
 }
 
-# @FUNCTION: distutils_src_test
-# @INTERNAL
-# @DESCRIPTION:
-# Die and warn when function from previous distutils is called
 distutils_src_test() {
 	die "${FUNCNAME}() is invalid for distutils-r1, you probably want: ${FUNCNAME/_/-r1_}"
 }
 
-# @FUNCTION: distutils_src_install
-# @INTERNAL
-# @DESCRIPTION:
-# Die and warn when function from previous distutils is called
 distutils_src_install() {
 	die "${FUNCNAME}() is invalid for distutils-r1, you probably want: ${FUNCNAME/_/-r1_}"
 }
 
-# @FUNCTION: distutils_pkg_postinst
-# @INTERNAL
-# @DESCRIPTION:
-# Die and warn when function from previous distutils is called
 distutils_pkg_postinst() {
 	die "${FUNCNAME}() is invalid for distutils-r1, and pkg_postinst is unnecessary"
 }
 
-# @FUNCTION: distutils_pkg_postrm
-# @INTERNAL
-# @DESCRIPTION:
-# Die and warn when function from previous distutils is called
 distutils_pkg_postrm() {
 	die "${FUNCNAME}() is invalid for distutils-r1, and pkg_postrm is unnecessary"
 }
diff --git a/eclass/docs.eclass b/eclass/docs.eclass
index a8b1549dda36..adacae4abda6 100644
--- a/eclass/docs.eclass
+++ b/eclass/docs.eclass
@@ -118,12 +118,11 @@ case ${DOCS_BUILDER} in
 		;;
 esac
 
-# @FUNCTION: python_append_deps
+# @FUNCTION: python_append_dep
 # @DESCRIPTION:
 # Appends [\${PYTHON_USEDEP}] to all dependencies
 # for python based DOCS_BUILDERs such as mkdocs or
 # sphinx.
-
 python_append_deps() {
 	debug-print-function ${FUNCNAME}
 
@@ -333,10 +332,5 @@ if [[ ${_DISTUTILS_R1} && ( ${DOCS_BUILDER}="mkdocs" || ${DOCS_BUILDER}="sphinx"
 	python_compile_all() { docs_compile; }
 fi
 
-# @ECLASS-VARIABLE: _DOCS
-# @INTERNAL
-# @DESCRIPTION:
-# Please document
-
 _DOCS=1
 fi
diff --git a/eclass/dotnet.eclass b/eclass/dotnet.eclass
index f15b7f55fcc2..ae861daf6e79 100644
--- a/eclass/dotnet.eclass
+++ b/eclass/dotnet.eclass
@@ -2,8 +2,7 @@
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: dotnet.eclass
-# @MAINTAINER:
-# dotnet@gentoo.org
+# @MAINTAINER: dotnet@gentoo.org
 # @SUPPORTED_EAPIS: 1 2 3 4 5 6 7
 # @BLURB: common settings and functions for mono and dotnet related packages
 # @DESCRIPTION:
diff --git a/eclass/ecm.eclass b/eclass/ecm.eclass
index 1d6d08e72a7d..c763957bf893 100644
--- a/eclass/ecm.eclass
+++ b/eclass/ecm.eclass
@@ -20,11 +20,6 @@
 # This eclass's phase functions are not intended to be mixed and matched, so if
 # any phase functions are overridden the version here should also be called.
 
-# @VARIABLE: _ECM_ECLASS
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
-
 if [[ -z ${_ECM_ECLASS} ]]; then
 _ECM_ECLASS=1
 
diff --git a/eclass/elisp-common.eclass b/eclass/elisp-common.eclass
index fb4498ae0867..66a3a325e673 100644
--- a/eclass/elisp-common.eclass
+++ b/eclass/elisp-common.eclass
@@ -272,8 +272,6 @@ elisp-check-emacs-version() {
 	fi
 }
 
-# @FUNCTION: elisp-need-emacs
-# @DESCRIPTION:
 # Test if the eselected Emacs version is at least the major version
 # of GNU Emacs specified as argument.
 # Return 0 if true, 1 if false, 2 if trouble.
diff --git a/eclass/emboss-r2.eclass b/eclass/emboss-r2.eclass
index b260cd2736bb..7d13f194eb7a 100644
--- a/eclass/emboss-r2.eclass
+++ b/eclass/emboss-r2.eclass
@@ -35,11 +35,6 @@
 #
 # Defaults to the upstream name of the module.
 
-# @VARIABLE: _EMBOSS_R2
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
-
 if [[ ! ${_EMBOSS_R2} ]]; then
 
 case ${EAPI:-0} in
diff --git a/eclass/epatch.eclass b/eclass/epatch.eclass
index 921647e257a6..fbb4f0b5bc0d 100644
--- a/eclass/epatch.eclass
+++ b/eclass/epatch.eclass
@@ -11,11 +11,6 @@
 # An eclass providing epatch and epatch_user functions to easily apply
 # patches to ebuilds. Mostly superseded by eapply* in EAPI 6.
 
-# @VARIABLE: _EPATCH_ECLASS
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
-
 if [[ -z ${_EPATCH_ECLASS} ]]; then
 
 case ${EAPI:-0} in
diff --git a/eclass/estack.eclass b/eclass/estack.eclass
index 37a2994283ce..c0823adb03f7 100644
--- a/eclass/estack.eclass
+++ b/eclass/estack.eclass
@@ -1,4 +1,4 @@
-# Copyright 1999-2019 Gentoo Authors
+# Copyright 1999-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: estack.eclass
@@ -8,11 +8,6 @@
 # @DESCRIPTION:
 # Support for storing values on stack-like variables.
 
-# @VARIABLE: _ESTACK_ECLASS
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
-
 if [[ -z ${_ESTACK_ECLASS} ]]; then
 
 # @FUNCTION: estack_push
diff --git a/eclass/eutils.eclass b/eclass/eutils.eclass
index 0750da6019e8..20ebe31c10a4 100644
--- a/eclass/eutils.eclass
+++ b/eclass/eutils.eclass
@@ -19,11 +19,6 @@
 # or eclasses.  Use the more specific split eclasses instead, or native
 # package manager functions when available.
 
-# @ECLASS-VARIABLE: _EUTILS_ECLASS
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
-
 if [[ -z ${_EUTILS_ECLASS} ]]; then
 _EUTILS_ECLASS=1
 
@@ -74,10 +69,6 @@ emktemp() {
 	fi
 }
 
-# @FUNCTION: path_exists
-# @DESCRIPTION:
-# Warn that function has been removed
-
 path_exists() {
 	eerror "path_exists has been removed.  Please see the following post"
 	eerror "for a replacement snippet:"
diff --git a/eclass/fcaps.eclass b/eclass/fcaps.eclass
index 107a519892dc..4bef00d40ac7 100644
--- a/eclass/fcaps.eclass
+++ b/eclass/fcaps.eclass
@@ -28,11 +28,6 @@
 # )
 # @CODE
 
-# @VARIABLE: _FCAPS_ECLASS
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
-
 if [[ -z ${_FCAPS_ECLASS} ]]; then
 _FCAPS_ECLASS=1
 
diff --git a/eclass/findlib.eclass b/eclass/findlib.eclass
index aedcc6fad008..8fc5fd625a17 100644
--- a/eclass/findlib.eclass
+++ b/eclass/findlib.eclass
@@ -1,4 +1,4 @@
-# Copyright 1999-2019 Gentoo Authors
+# Copyright 1999-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: findlib.eclass
@@ -16,10 +16,6 @@
 DEPEND=">=dev-ml/findlib-1.0.4-r1"
 [[ ${FINDLIB_USE} ]] && DEPEND="${FINDLIB_USE}? ( ${DEPEND} )"
 
-# @FUNCTION: check_ocamlfind
-# @DESCRIPTION:
-# Please document me
-
 check_ocamlfind() {
 	if [ ! -x "${EPREFIX}"/usr/bin/ocamlfind ]
 	then
diff --git a/eclass/fixheadtails.eclass b/eclass/fixheadtails.eclass
index 23f14692d5ce..475b182843a5 100644
--- a/eclass/fixheadtails.eclass
+++ b/eclass/fixheadtails.eclass
@@ -8,11 +8,6 @@
 # Original author John Mylchreest <johnm@gentoo.org>
 # @BLURB: functions to replace obsolete head/tail with POSIX compliant ones
 
-# @FUNCTION: _do_sed_fix
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
-
 _do_sed_fix() {
 	einfo " - fixed $1"
 	sed -i \
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=()
diff --git a/eclass/font-ebdftopcf.eclass b/eclass/font-ebdftopcf.eclass
index 9e00eec467f2..29568e560134 100644
--- a/eclass/font-ebdftopcf.eclass
+++ b/eclass/font-ebdftopcf.eclass
@@ -1,15 +1,12 @@
 # Copyright 1999-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
-# @ECLASS: font-ebdftopcf.eclass
-# @MAINTAINER:
-# Robin H. Johnson <robbat2@gentoo.org>
-# @AUTHOR:
-# Robin H. Johnson <robbat2@gentoo.org>
-# @BLURB: A simple eclass to convert BDF to PCF
-# @DESCRIPTION:
-# Make PCF font generator from BDF uniform and optimal
+# Author: Robin H. Johnson <robbat2@gentoo.org>
+
+# font-ebdftopcf.eclass
+# Eclass to make PCF font generator from BDF uniform and optimal
 # The manpage for this eclass is in media-gfx/ebdftopcf.
+
 # inherit this eclass after font.eclass
 
 # if USE="-X", this eclass is basically a no-op, since bdftopcf requires Xorg.
@@ -19,9 +16,9 @@ IUSE="X"
 DEPEND="X? ( media-gfx/ebdftopcf )"
 RDEPEND=""
 
-# @FUNCTION: ebdftopcf
-# @DESCRIPTION:
-# Convert BDF files to PCF
+#
+# Public functions
+#
 ebdftopcf() {
 	local bdffiles
 	bdffiles="$@"
@@ -32,9 +29,9 @@ ebdftopcf() {
 		|| die "Failed to build PCF files"
 }
 
-# @FUNCTION: font-ebdftopcf_src_compile
-# @DESCRIPTION:
-# Convert fonts from BDF to PCF
+#
+# Public inheritable functions
+#
 font-ebdftopcf_src_compile() {
 	use X && FONT_SUFFIX="pcf.gz"
 	use X || FONT_SUFFIX="bdf"
diff --git a/eclass/font.eclass b/eclass/font.eclass
index 10f4bf61e8d7..e9e448a8155b 100644
--- a/eclass/font.eclass
+++ b/eclass/font.eclass
@@ -13,11 +13,6 @@ case ${EAPI:-0} in
 	*) die "EAPI ${EAPI} is not supported by font.eclass." ;;
 esac
 
-# @VARIABLE: _FONT_ECLASS
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
-
 if [[ ! ${_FONT_ECLASS} ]]; then
 
 EXPORT_FUNCTIONS pkg_setup src_install pkg_postinst pkg_postrm
diff --git a/eclass/fortran-2.eclass b/eclass/fortran-2.eclass
index 45f26a83c2b0..6049b03b8f14 100644
--- a/eclass/fortran-2.eclass
+++ b/eclass/fortran-2.eclass
@@ -36,11 +36,6 @@ esac
 
 EXPORT_FUNCTIONS pkg_setup
 
-# @VARIABLE: _FORTRAN_2_CLASS
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
-
 if [[ ! ${_FORTRAN_2_CLASS} ]]; then
 
 # @ECLASS-VARIABLE: FORTRAN_NEED_OPENMP
@@ -287,10 +282,5 @@ fortran-2_pkg_setup() {
 	fi
 }
 
-# @VARIABLE: _FORTRAN_2_ECLASS
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
-
 _FORTRAN_2_ECLASS=1
 fi
diff --git a/eclass/games.eclass b/eclass/games.eclass
index cdd40a222572..a2a5ce066a57 100644
--- a/eclass/games.eclass
+++ b/eclass/games.eclass
@@ -26,10 +26,6 @@
 # is needed. For more details, see the QA team policies page:
 # https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Policies#Games
 
-# @VARIABLE: _GAMES_ECLASS
-# @INTERNAL
-# @DESCRIPTION:
-# Please document me
 
 if [[ -z ${_GAMES_ECLASS} ]]; then
 _GAMES_ECLASS=1
diff --git a/eclass/gnuconfig.eclass b/eclass/gnuconfig.eclass
index 6ddaabff00a6..3433837787c2 100644
--- a/eclass/gnuconfig.eclass
+++ b/eclass/gnuconfig.eclass
@@ -1,13 +1,8 @@
 # Copyright 1999-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
-
-# @ECLASS: gnuconfig.eclass
-# @MAINTAINER:
-# maintainer-needed@gentoo.org
-# @AUTHOR:
-# Will Woods <wwoods@gentoo.org>
-# @BLURB: Automatically update automake files to newest version
-# @DESCRIPTION:
+#
+# Author: Will Woods <wwoods@gentoo.org>
+#
 # This eclass is used to automatically update files that typically come with
 # automake to the newest version available on the system. The most common use
 # of this is to update config.guess and config.sub when configure dies from
@@ -25,8 +20,6 @@
 
 DEPEND="sys-devel/gnuconfig"
 
-# @FUNCTION: gnuconfig_update
-# @DESCRIPTION:
 # Wrapper function for gnuconfig_do_update. If no arguments are given, update
 # config.sub and config.guess (old default behavior), otherwise update the
 # named files.
@@ -49,12 +42,10 @@ gnuconfig_update() {
 	return $?
 }
 
-# @FUNCTION: gnuconfig_do_update
-# @DESCRIPTION:
 # Copy the newest available version of specified files over any old ones in the
 # source dir. This function shouldn't be called directly - use gnuconfig_update
 #
-# Note: that since bash using dynamic scoping, startdir is available here from
+# Note that since bash using dynamic scoping, startdir is available here from
 # the gnuconfig_update function
 gnuconfig_do_update() {
 	local configsubs_dir target targetlist file
@@ -84,8 +75,6 @@ gnuconfig_do_update() {
 	return 0
 }
 
-# @FUNCTION: gnuconfig_findnewest
-# @DESCRIPTION:
 # this searches the standard locations for the newest config.{sub|guess}, and
 # returns the directory where they can be found.
 gnuconfig_findnewest() {
diff --git a/eclass/golang-vcs-snapshot.eclass b/eclass/golang-vcs-snapshot.eclass
index 1048cef492ea..306db1f26c98 100644
--- a/eclass/golang-vcs-snapshot.eclass
+++ b/eclass/golang-vcs-snapshot.eclass
@@ -1,11 +1,12 @@
-# Copyright 1999-2019 Gentoo Authors
+# Copyright 1999-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: golang-vcs-snapshot.eclass
 # @MAINTAINER:
 # William Hubbs <williamh@gentoo.org>
 # @SUPPORTED_EAPIS: 5 6 7
-# @BLURB: support eclass for unpacking VCS snapshot tarballs
+# @BLURB: support eclass for unpacking VCS snapshot tarballs for
+# software written in the Go programming language
 # @DESCRIPTION:
 # This eclass provides a convenience src_unpack() which unpacks the
 # first tarball mentioned in SRC_URI to its appropriate location in
@@ -62,10 +63,6 @@ EXPORT_FUNCTIONS src_unpack
 declare -arg EGO_VENDOR
 
 _golang-vcs-snapshot_set_vendor_uri() {
-	# @ECLASS-VARIABLE: EGO_VENDOR_URI
-	# @DEFAULT_UNSET
-	# @DESCRIPTION:
-	# Determine the appropriate vendor URI
 	EGO_VENDOR_URI=
 	local lib
 	for lib in "${EGO_VENDOR[@]}"; do
diff --git a/eclass/java-utils-2.eclass b/eclass/java-utils-2.eclass
index 84c09885c7ba..b0d4d8acbefc 100644
--- a/eclass/java-utils-2.eclass
+++ b/eclass/java-utils-2.eclass
@@ -1,4 +1,4 @@
-# Copyright 2004-2018 Gentoo Authors
+# Copyright 2004-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: java-utils-2.eclass
@@ -1484,6 +1484,7 @@ java-pkg_ensure-vm-version-sufficient() {
 
 # @FUNCTION: java-pkg_is-vm-version-sufficient
 # @INTERNAL
+# @DESCRIPTION:
 # @RETURN: zero - VM is sufficient; non-zero - VM is not sufficient
 java-pkg_is-vm-version-sufficient() {
 	debug-print-function ${FUNCNAME} $*
@@ -1563,8 +1564,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
-# @RETURN: non-zero - current VM version is not greater than checked version
+# @RETURN: zero - current VM version is greater than checked version;
+# 	non-zero - current VM version is not greater than checked version
 java-pkg_is-vm-version-ge() {
 	debug-print-function ${FUNCNAME} $*
 
@@ -2591,14 +2592,14 @@ java-pkg_needs-vm() {
 
 # @FUNCTION: java-pkg_get-current-vm
 # @INTERNAL
-# @RETURN: The current VM being used
+# @RETURN - The current VM being used
 java-pkg_get-current-vm() {
 	java-config -f
 }
 
 # @FUNCTION: java-pkg_get-vm-vendor
 # @INTERNAL
-# @RETURN: The vendor of the current VM
+# @RETURN - The vendor of the current VM
 java-pkg_get-vm-vendor() {
 	debug-print-function ${FUNCNAME} $*
 
@@ -2609,7 +2610,7 @@ java-pkg_get-vm-vendor() {
 
 # @FUNCTION: java-pkg_get-vm-version
 # @INTERNAL
-# @RETURN: The version of the current VM
+# @RETURN - The version of the current VM
 java-pkg_get-vm-version() {
 	debug-print-function ${FUNCNAME} $*
 
diff --git a/eclass/mozextension.eclass b/eclass/mozextension.eclass
index 2e51180f1e51..c6276908b9f5 100644
--- a/eclass/mozextension.eclass
+++ b/eclass/mozextension.eclass
@@ -5,9 +5,7 @@
 # @MAINTAINER:
 # Mozilla team <mozilla@gentoo.org>
 # @BLURB: Install extensions for use in mozilla products.
-# @DESCRIPTION:
-# Install extensions for use in mozilla products
-
+#
 if [[ ! ${_MOZEXTENSION} ]]; then
 
 # @ECLASS-VARIABLE: MOZEXTENSION_TARGET
@@ -22,10 +20,6 @@ inherit eutils
 
 DEPEND="app-arch/unzip"
 
-# @FUNCTION: mozversion_extension_location
-# @DESCRIPTION:
-# Get ${PN} from extension location
-
 mozversion_extension_location() {
 	case ${PN} in
 		firefox|firefox-bin|palemoon)
@@ -38,10 +32,6 @@ mozversion_extension_location() {
 	return 1
 }
 
-# @FUNCTION: xpi_unpack
-# @DESCRIPTION:
-# Unpack XPI files
-
 xpi_unpack() {
 	local xpi xpiname srcdir
 
@@ -71,9 +61,6 @@ xpi_unpack() {
 	done
 }
 
-# @FUNCTION: xpi_install
-# @DESCRIPTION:
-# Install XPI files
 
 xpi_install() {
 	local emid
@@ -104,10 +91,6 @@ xpi_install() {
 	doins -r "${x}"/* || die "failed to copy extension"
 }
 
-# @FUNCTION: xpi_copy
-# @DESCRIPTION:
-# Copy XPI files
-
 xpi_copy() {
 	local emid
 
diff --git a/eclass/myspell-r2.eclass b/eclass/myspell-r2.eclass
index 088edf4e4a85..2de8d14c78b1 100644
--- a/eclass/myspell-r2.eclass
+++ b/eclass/myspell-r2.eclass
@@ -7,6 +7,7 @@
 # @AUTHOR:
 # Tomáš Chvátal <scarabeus@gentoo.org>
 # @BLURB: An eclass to ease the construction of ebuilds for myspell dicts
+# @DESCRIPTION:
 
 EXPORT_FUNCTIONS src_unpack src_install
 
diff --git a/eclass/openib.eclass b/eclass/openib.eclass
index 685eaf344a7e..a36f5cd85d02 100644
--- a/eclass/openib.eclass
+++ b/eclass/openib.eclass
@@ -2,10 +2,8 @@
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: openib.eclass
-# @MAINTAINER:
-# maintainer-needed@gentoo.org
 # @AUTHOR:
-# Alexey Shvetsov <alexxy@gentoo.org>
+# Original Author: Alexey Shvetsov <alexxy@gentoo.org>
 # @BLURB: Simplify working with OFED packages
 
 inherit eutils rpm versionator
diff --git a/eclass/php-pear-r2.eclass b/eclass/php-pear-r2.eclass
index cd4625fdacc2..d3887492047d 100644
--- a/eclass/php-pear-r2.eclass
+++ b/eclass/php-pear-r2.eclass
@@ -1,4 +1,4 @@
-# Copyright 1999-2018 Gentoo Authors
+# Copyright 1999-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: php-pear-r2.eclass
@@ -39,8 +39,7 @@ RDEPEND=">=dev-php/pear-1.8.1"
 
 # @ECLASS-VARIABLE: PEAR-P
 # @INTERNAL
-# @DESCRIPTION:
-# Combines PHP_PEAR_PKG_NAME and PEAR_PV
+# @DESCRIPTION: Combines PHP_PEAR_PKG_NAME and PEAR_PV
 PEAR_P="${PHP_PEAR_PKG_NAME}-${PEAR_PV}"
 
 # @ECLASS-VARIABLE: PHP_PEAR_DOMAIN
diff --git a/eclass/portability.eclass b/eclass/portability.eclass
index 4a318178c72b..333a9590b39c 100644
--- a/eclass/portability.eclass
+++ b/eclass/portability.eclass
@@ -13,6 +13,7 @@ _PORTABILITY_ECLASS=1
 
 # @FUNCTION: treecopy
 # @USAGE: <orig1> [orig2 orig3 ....] <dest>
+# @RETURN:
 # @DESCRIPTION:
 # mimic cp --parents copy, but working on BSD userland as well
 treecopy() {
@@ -117,6 +118,7 @@ get_bmake() {
 # @FUNCTION: get_mounts
 # @USAGE:
 # @RETURN: table of mounts in form "point node fs opts"
+# @MAINTAINER:
 # @DESCRIPTION:
 # Portable method of getting mount names and points.
 # Returns as "point node fs options"
diff --git a/eclass/postgres-multi.eclass b/eclass/postgres-multi.eclass
index 76916932042d..49d5c6a9c684 100644
--- a/eclass/postgres-multi.eclass
+++ b/eclass/postgres-multi.eclass
@@ -8,8 +8,7 @@ EXPORT_FUNCTIONS pkg_setup src_prepare src_compile src_install src_test
 # @ECLASS: postgres-multi.eclass
 # @MAINTAINER:
 # PostgreSQL <pgsql-bugs@gentoo.org>
-# @AUTHOR:
-# Aaron W. Swenson <titanofold@gentoo.org>
+# @AUTHOR: Aaron W. Swenson <titanofold@gentoo.org>
 # @SUPPORTED_EAPIS: 5 6 7
 # @BLURB: An eclass to build PostgreSQL-related packages against multiple slots
 # @DESCRIPTION:
diff --git a/eclass/postgres.eclass b/eclass/postgres.eclass
index b7b45fd888d4..2e2ac85ead6f 100644
--- a/eclass/postgres.eclass
+++ b/eclass/postgres.eclass
@@ -7,8 +7,7 @@ EXPORT_FUNCTIONS pkg_setup
 # @ECLASS: postgres.eclass
 # @MAINTAINER:
 # PostgreSQL <pgsql-bugs@gentoo.org>
-# @AUTHOR:
-# Aaron W. Swenson <titanofold@gentoo.org>
+# @AUTHOR: Aaron W. Swenson <titanofold@gentoo.org>
 # @SUPPORTED_EAPIS: 5 6 7
 # @BLURB: An eclass for PostgreSQL-related packages
 # @DESCRIPTION:
diff --git a/eclass/rebar.eclass b/eclass/rebar.eclass
index 17be853acfaa..7f712905c407 100644
--- a/eclass/rebar.eclass
+++ b/eclass/rebar.eclass
@@ -54,8 +54,8 @@ get_erl_libs() {
 # @INTERNAL
 # @USAGE: <project_name>
 # @RETURN: full path with EPREFIX to a Erlang package/project on success,
-# @RETURN: code 1 when dependency is not found and code 2 if multiple versions of
-# @RETURN: dependency are found.
+# code 1 when dependency is not found and code 2 if multiple versions of
+# dependency are found.
 # @DESCRIPTION:
 # Find a Erlang package/project by name in Erlang lib directory. Project
 # directory is usually suffixed with version. It is matched to '<project_name>'
diff --git a/eclass/ruby-ng.eclass b/eclass/ruby-ng.eclass
index 628d04592abd..e52c507d8010 100644
--- a/eclass/ruby-ng.eclass
+++ b/eclass/ruby-ng.eclass
@@ -111,7 +111,6 @@ ruby_implementation_depend() {
 # @FUNCTION: _ruby_get_all_impls
 # @INTERNAL
 # @RETURN: list of valid values in USE_RUBY
-# @DESCRIPTION:
 # Return a list of valid implementations in USE_RUBY, skipping the old
 # implementations that are no longer supported.
 _ruby_get_all_impls() {
diff --git a/eclass/ssl-cert.eclass b/eclass/ssl-cert.eclass
index c984cb3bfd3f..fdd6775ffc77 100644
--- a/eclass/ssl-cert.eclass
+++ b/eclass/ssl-cert.eclass
@@ -1,9 +1,8 @@
-# Copyright 1999-2019 Gentoo Authors
+# Copyright 1999-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: ssl-cert.eclass
 # @MAINTAINER:
-# maintainer-needed@gentoo.org
 # @AUTHOR:
 # Max Kalika <max@gentoo.org>
 # @SUPPORTED_EAPIS: 1 2 3 4 5 6 7
diff --git a/eclass/stardict.eclass b/eclass/stardict.eclass
index 075c832829bf..5e96b01625cd 100644
--- a/eclass/stardict.eclass
+++ b/eclass/stardict.eclass
@@ -1,14 +1,11 @@
 # Copyright 1999-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
-# @ECLASS: stardict.eclass
-# @MAINTAINER:
-# maintainer-needed@gentoo.org
-# @AUTHOR:
-# Alastair Tse <liquidx@gentoo.org>
-# @BLURB: eclass to do stardict dictionary installations.
-
-# @Usage:
+# Author : Alastair Tse <liquidx@gentoo.org>
+#
+# Convienence class to do stardict dictionary installations.
+#
+# Usage:
 #   - Variables to set :
 #      * FROM_LANG     -  From this language
 #      * TO_LANG       -  To this language
diff --git a/eclass/toolchain.eclass b/eclass/toolchain.eclass
index 095c53d4c1d8..59f8660a3d90 100644
--- a/eclass/toolchain.eclass
+++ b/eclass/toolchain.eclass
@@ -1,14 +1,8 @@
 # Copyright 1999-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
-# @ECLASS: toolchain.eclass
-# @MAINTAINER:
-# Toolchain Ninjas <toolchain@gentoo.org>
-# @AUTHOR:
-# Toolchain Ninjas <toolchain@gentoo.org>
+# Maintainer: Toolchain Ninjas <toolchain@gentoo.org>
 # @SUPPORTED_EAPIS: 5 6 7
-# @BLURB: Basic toolchain stuff
-
 
 DESCRIPTION="The GNU Compiler Collection"
 HOMEPAGE="https://gcc.gnu.org/"
diff --git a/eclass/vim-doc.eclass b/eclass/vim-doc.eclass
index 99b5d6b2d550..70a6e943e85f 100644
--- a/eclass/vim-doc.eclass
+++ b/eclass/vim-doc.eclass
@@ -1,11 +1,6 @@
 # Copyright 1999-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
-
-# @ECLASS: vim-doc.eclass
-# @MAINTAINER:
-# Vim project <vim@gentoo.org>
-# @BLURB: Work with Vim documentation
-# @DESCRIPTION:
+#
 # This eclass is used by vim.eclass and vim-plugin.eclass to update
 # the documentation tags.  This is necessary since vim doesn't look in
 # /usr/share/vim/vimfiles/doc for documentation; it only uses the