Add eclass documentation.

1 files changed, 79 insertions, 21 deletions

diff --git a/eclass/gnome2-utils.eclass b/eclass/gnome2-utils.eclass
index 1f3c466ca5f9..c599f140dd21 100644
--- a/eclass/gnome2-utils.eclass
+++ b/eclass/gnome2-utils.eclass
@@ -1,44 +1,82 @@
 # Copyright 1999-2006 Gentoo Foundation
 # Distributed under the terms of the GNU General Public License v2
-# $Header: /var/cvsroot/gentoo-x86/eclass/gnome2-utils.eclass,v 1.21 2011/01/31 17:03:45 eva Exp $
-
-#
-# gnome2-utils.eclass
-#
-# Set of auxiliary functions used to perform actions commonly needed by packages
-# using the GNOME framework.
-#
-# Maintained by Gentoo's GNOME herd <gnome@gentoo.org>
-#
+# $Header: /var/cvsroot/gentoo-x86/eclass/gnome2-utils.eclass,v 1.22 2011/04/03 18:12:34 eva Exp $
+
+# @ECLASS: gnome2-utils.eclass
+# @MAINTAINER: 
+# gnome@gentoo.org
+# @BLURB: Auxiliary functions commonly used by Gnome packages.
+# @DESCRIPTION:
+# This eclass provides a set of auxiliary functions needed by most Gnome
+# packages. It may be used by non-Gnome packages as needed for handling various
+# Gnome stack related functions such as:
+#  * Gtk+ icon cache management
+#  * GSettings schemas management
+#  * GConf schemas management
+#  * scrollkeeper (old Gnome help system) management
 
 case "${EAPI:-0}" in
 	0|1|2|3|4) ;;
 	*) die "EAPI=${EAPI} is not supported" ;;
 esac
 
+# @ECLASS-VARIABLE: GCONFTOOL_BIN
+# @INTERNAL
+# @DESCRIPTION:
 # Path to gconftool-2
 : ${GCONFTOOL_BIN:="/usr/bin/gconftool-2"}
 
+# @ECLASS-VARIABLE: SCROLLKEEPER_DIR
+# @INTERNAL
+# @DESCRIPTION:
 # Directory where scrollkeeper-update should do its work
 : ${SCROLLKEEPER_DIR:="/var/lib/scrollkeeper"}
 
+# @ECLASS-VARIABLE: SCROLLKEEPER_UPDATE_BIN
+# @INTERNAL
+# @DESCRIPTION:
 # Path to scrollkeeper-update
 : ${SCROLLKEEPER_UPDATE_BIN:="/usr/bin/scrollkeeper-update"}
 
+# @ECLASS-VARIABLE: GTK_UPDATE_ICON_CACHE
+# @INTERNAL
+# @DESCRIPTION:
 # Path to gtk-update-icon-cache
 : ${GTK_UPDATE_ICON_CACHE:="/usr/bin/gtk-update-icon-cache"}
 
+# @ECLASS-VARIABLE: GLIB_COMPILE_SCHEMAS
+# @INTERNAL
+# @DESCRIPTION:
 # Path to glib-compile-schemas
 : ${GLIB_COMPILE_SCHEMAS:="/usr/bin/glib-compile-schemas"}
 
+# @ECLASS-VARIABLE: GNOME2_ECLASS_SCHEMAS
+# @INTERNAL
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# List of GConf schemas provided by the package
 
+# @ECLASS-VARIABLE: GNOME2_ECLASS_ICONS
+# @INTERNAL
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# List of icons provided by the package
 
-DEPEND=">=sys-apps/sed-4"
+# @ECLASS-VARIABLE: GNOME2_ECLASS_GLIB_SCHEMAS
+# @INTERNAL
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# List of GSettings schemas provided by the package
 
 
+DEPEND=">=sys-apps/sed-4"
 
+
+# @FUNCTION: gnome2_gconf_savelist
+# @DESCRIPTION:
 # Find the GConf schemas that are about to be installed and save their location
-# in the GNOME2_ECLASS_SCHEMAS environment variable
+# in the GNOME2_ECLASS_SCHEMAS environment variable.
+# This function should be called from pkg_preinst.
 gnome2_gconf_savelist() {
 	has ${EAPI:-0} 0 1 2 && ! use prefix && ED="${D}"
 	pushd "${ED}" &> /dev/null
@@ -46,9 +84,11 @@ gnome2_gconf_savelist() {
 	popd &> /dev/null
 }
 
-
+# @FUNCTION: gnome2_gconf_install
+# @DESCRIPTION:
 # Applies any schema files installed by the current ebuild to Gconf's database
-# using gconftool-2
+# using gconftool-2.
+# This function should be called from pkg_postinst.
 gnome2_gconf_install() {
 	has ${EAPI:-0} 0 1 2 && ! use prefix && EROOT="${ROOT}"
 	local updater="${EROOT}${GCONFTOOL_BIN}"
@@ -86,7 +126,8 @@ gnome2_gconf_install() {
 	fi
 }
 
-
+# @FUNCTION: gnome2_gconf_uninstall
+# @DESCRIPTION:
 # Removes schema files previously installed by the current ebuild from Gconf's
 # database.
 gnome2_gconf_uninstall() {
@@ -125,10 +166,11 @@ gnome2_gconf_uninstall() {
 	fi
 }
 
-
+# @FUNCTION: gnome2_icon_savelist
+# @DESCRIPTION:
 # Find the icons that are about to be installed and save their location
-# in the GNOME2_ECLASS_ICONS environment variable
-# That function should be called from pkg_preinst
+# in the GNOME2_ECLASS_ICONS environment variable.
+# This function should be called from pkg_preinst.
 gnome2_icon_savelist() {
 	has ${EAPI:-0} 0 1 2 && ! use prefix && ED="${D}"
 	pushd "${ED}" &> /dev/null
@@ -136,9 +178,11 @@ gnome2_icon_savelist() {
 	popd &> /dev/null
 }
 
-
+# @FUNCTION: gnome2_icon_cache_update
+# @DESCRIPTION:
 # Updates Gtk+ icon cache files under /usr/share/icons if the current ebuild
 # have installed anything under that location.
+# This function should be called from pkg_postinst and pkg_postrm.
 gnome2_icon_cache_update() {
 	has ${EAPI:-0} 0 1 2 && ! use prefix && EROOT="${ROOT}"
 	local updater="${EROOT}${GTK_UPDATE_ICON_CACHE}"
@@ -184,9 +228,11 @@ gnome2_icon_cache_update() {
 	done
 }
 
-
+# @FUNCTION: gnome2_omf_fix
+# @DESCRIPTION:
 # Workaround applied to Makefile rules in order to remove redundant
 # calls to scrollkeeper-update and sandbox violations.
+# This function should be called from src_prepare.
 gnome2_omf_fix() {
 	local omf_makefiles filename
 
@@ -231,8 +277,10 @@ gnome2_omf_fix() {
 	done
 }
 
-
+# @FUNCTION: gnome2_scrollkeeper_update
+# @DESCRIPTION:
 # Updates the global scrollkeeper database.
+# This function should be called from pkg_postinst and pkg_postrm.
 gnome2_scrollkeeper_update() {
 	has ${EAPI:-0} 0 1 2 && ! use prefix && EROOT="${ROOT}"
 	if [[ -x "${EROOT}${SCROLLKEEPER_UPDATE_BIN}" ]]; then
@@ -241,6 +289,11 @@ gnome2_scrollkeeper_update() {
 	fi
 }
 
+# @FUNCTION: gnome2_schemas_savelist
+# @DESCRIPTION:
+# Find if there is any GSettings schema to install and save the list in
+# GNOME2_ECLASS_GLIB_SCHEMAS variable.
+# This function should be called from pkg_preinst.
 gnome2_schemas_savelist() {
 	has ${EAPI:-0} 0 1 2 && ! use prefix && ED="${D}"
 	pushd "${ED}" &>/dev/null
@@ -248,6 +301,11 @@ gnome2_schemas_savelist() {
 	popd &>/dev/null
 }
 
+# @FUNCTION: gnome2_schemas_update
+# @USAGE: gnome2_schemas_update [--uninstall]
+# @DESCRIPTION:
+# Updates GSettings schemas if GNOME2_ECLASS_GLIB_SCHEMAS has some.
+# This function should be called from pkg_postinst and pkg_postrm with --uninstall.
 gnome2_schemas_update() {
 	has ${EAPI:-0} 0 1 2 && ! use prefix && EROOT="${ROOT}"
 	local updater="${EROOT}${GLIB_COMPILE_SCHEMAS}"