[gentoo-commits] proj/sci:master commit in: eclass/

["Reinis Danne" <rei4dan@gmail.com>]

commit:     ff8b1ad72e5f30ec5b3f084b87c672f2a7b81c6f
Author:     Reinis Danne <rei4dan <AT> gmail <DOT> com>
AuthorDate: Mon Jan 20 16:35:24 2014 +0000
Commit:     Reinis Danne <rei4dan <AT> gmail <DOT> com>
CommitDate: Tue Jan 21 19:55:21 2014 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/sci.git;a=commit;h=ff8b1ad7

alternatives-2.eclass: Add documentation comments

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

diff --git a/eclass/alternatives-2.eclass b/eclass/alternatives-2.eclass
index f83c479..bc60108 100644
--- a/eclass/alternatives-2.eclass
+++ b/eclass/alternatives-2.eclass
@@ -7,6 +7,16 @@
 # Copyright 2008, 2009 Mike Kelly
 # Copyright 2009 David Leverton
 
+# @ECLASS: alternatives-2
+# @MAINTAINER:
+# Gentoo Science Project <sci@gentoo.org>
+# @BLURB: Manage alternative implementations.
+# @DESCRIPTION:
+# Autogenerate eselect modules for alternatives and ensure that valid provider
+# is set.
+#
+# Remove eselect modules when last provider is unmerged.
+#
 # 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 +31,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 +39,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 +129,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 +144,14 @@ cleanup_old_alternatives_module() {
 	fi
 }
 
+# @FUNCTION: alternatives-2_pkg_postinst
+# @DESCRIPTION:
+# Create eselect modules for all provided alternatives if necessary and ensure
+# that valid provider is set.
+#
+# Also remove old eselect modules for 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 +184,13 @@ alternatives-2_pkg_postinst() {
 	done
 }
 
+# @FUNCTION: alternatives-2_pkg_prerm
+# @DESCRIPTION:
+# Ensure a valid provider is set in case the package is unmerged and
+# remove autogenerated eselect modules for all alternatives when last
+# provider is unmerged.
+#
+# 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"