[gentoo-science] [PATCH 08/10] alternatives-2.eclass: Add documentation comments

[Reinis Danne]

---
 eclass/alternatives-2.eclass | 41 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 37 insertions(+), 4 deletions(-)

diff --git a/eclass/alternatives-2.eclass b/eclass/alternatives-2.eclass
index 5128e11..e15edfa 100644
--- a/eclass/alternatives-2.eclass
+++ b/eclass/alternatives-2.eclass
@@ -7,6 +7,12 @@
 # Copyright 2008, 2009 Mike Kelly
 # Copyright 2009 David Leverton
 
+# @ECLASS: alternatives-2
+# @MAINTAINER:
+# Gentoo Science Project <sci@g.o>
+# @BLURB: Manage alternative implementations.
+# @DESCRIPTION:
+#
 # If your package provides pkg_postinst or pkg_prerm phases, you need to be
 # sure you explicitly run alternatives-2_pkg_{postinst,prerm} where appropriate.
 
@@ -21,8 +27,6 @@ case "${EAPI:-0}" in
 		;;
 esac
 
-ALTERNATIVES_DIR="/etc/env.d/alternatives"
-
 DEPEND=">=app-admin/eselect-1.4-r100"
 RDEPEND="${DEPEND}
 	!app-admin/eselect-blas
@@ -31,9 +35,24 @@ RDEPEND="${DEPEND}
 
 EXPORT_FUNCTIONS pkg_postinst pkg_prerm
 
-# alternatives_for alternative provider importance source target [ source target [...]]
-alternatives_for() {
+# @ECLASS-VARIABLE: ALTERNATIVES_DIR
+# @INTERNAL
+# @DESCRIPTION:
+# Alternatives directory with symlinks managed by eselect.
+ALTERNATIVES_DIR="/etc/env.d/alternatives"
 
+# @FUNCTION: alternatives_for
+# @USAGE: alternative provider importance source target [source target [...]]
+# @DESCRIPTION:
+# Set up alternative provider.
+#
+# EXAMPLE:
+# @CODE
+# alternatives_for cblas atlas 0 \
+#     /usr/$(get_libdir)/pkgconfig/cblas.pc atlas-cblas.pc \
+#     /usr/include/cblas.h atlas/cblas.h
+# @CODE
+alternatives_for() {
 	(( $# >= 5 )) && (( ($#-3)%2 == 0)) || die "${FUNCNAME} requires exactly 3+N*2 arguments where N>=1"
 	local alternative=${1} provider=${2} importance=${3} index src target ret=0
 	shift 3
@@ -106,6 +125,10 @@ alternatives_for() {
 	[[ ${ret} -eq 0 ]] || die "Errors detected for ${provider}, provided for ${alternative}"
 }
 
+# @FUNCTION: cleanup_old_alternatives_module
+# @USAGE: alternative
+# @DESCRIPTION:
+# Remove old alternatives module.
 cleanup_old_alternatives_module() {
 	local alt=${1} old_module="${EROOT%/}/usr/share/eselect/modules/${alt}.eselect"
 	if [[ -f "${old_module}" && "$(source "${old_module}" &>/dev/null; echo "${ALTERNATIVE}")" == "${alt}" ]]; then
@@ -117,6 +140,11 @@ cleanup_old_alternatives_module() {
 	fi
 }
 
+# @FUNCTION: alternatives-2_pkg_postinst
+# @DESCRIPTION:
+# Create eselect modules for all provided alternatives.
+#
+# Provided alternatives are set up using alternatives_for().
 alternatives-2_pkg_postinst() {
 	local a alt provider module_version="20090908"
 	local EAUTO="${EROOT%/}/usr/share/eselect/modules/auto"
@@ -149,6 +177,11 @@ alternatives-2_pkg_postinst() {
 	done
 }
 
+# @FUNCTION: alternatives-2_pkg_prerm
+# @DESCRIPTION:
+# Remove autogenerated eselect modules for all alternatives.
+#
+# Provided alternatives are set up using alternatives_for().
 alternatives-2_pkg_prerm() {
 	local a alt provider ignore
 	local EAUTO="${EROOT%/}/usr/share/eselect/modules/auto"
-- 
1.8.5.3