Update eclass documentation.

1 files changed, 49 insertions, 6 deletions

diff --git a/eclass/elisp.eclass b/eclass/elisp.eclass
index 502518d6352c..306b56b8e624 100644
--- a/eclass/elisp.eclass
+++ b/eclass/elisp.eclass
@@ -1,10 +1,10 @@
 # Copyright 1999-2010 Gentoo Foundation
 # Distributed under the terms of the GNU General Public License v2
-# $Header: /var/cvsroot/gentoo-x86/eclass/elisp.eclass,v 1.45 2010/08/22 08:30:32 ulm Exp $
+# $Header: /var/cvsroot/gentoo-x86/eclass/elisp.eclass,v 1.46 2010/09/17 07:39:58 ulm Exp $
 #
 # Copyright 2002-2003 Matthew Kennedy <mkennedy@gentoo.org>
 # Copyright 2003      Jeremy Maitin-Shepard <jbms@attbi.com>
-# Copyright 2007-2009 Christian Faulhammer <fauli@gentoo.org>
+# Copyright 2007-2010 Christian Faulhammer <fauli@gentoo.org>
 # Copyright 2007-2010 Ulrich Müller <ulm@gentoo.org>
 #
 # @ECLASS: elisp.eclass
@@ -15,7 +15,7 @@
 # @DESCRIPTION:
 #
 # This eclass is designed to install elisp files of Emacs related
-# packages into the site-lisp directory. The majority of elisp packages
+# packages into the site-lisp directory.  The majority of elisp packages
 # will only need to define the standard ebuild variables (like SRC_URI)
 # and optionally SITEFILE for successful installation.
 #
@@ -37,8 +37,8 @@
 # @ECLASS-VARIABLE: ELISP_PATCHES
 # @DEFAULT_UNSET
 # @DESCRIPTION:
-# Any patches to apply after unpacking the sources. Patches are searched
-# both in ${PWD} and ${FILESDIR}.
+# Any patches to apply after unpacking the sources.  Patch files are
+# searched for in the current working dir, WORKDIR, and FILESDIR.
 
 # @ECLASS-VARIABLE: SITEFILE
 # @DEFAULT_UNSET
@@ -51,7 +51,7 @@
 # @ECLASS-VARIABLE: ELISP_TEXINFO
 # @DEFAULT_UNSET
 # @DESCRIPTION:
-# Space separated list of Texinfo sources. Respective GNU Info files
+# Space separated list of Texinfo sources.  Respective GNU Info files
 # will be generated in src_compile() and installed in src_install().
 
 # @ECLASS-VARIABLE: DOCS
@@ -73,6 +73,11 @@ DEPEND=">=virtual/emacs-${NEED_EMACS:-21}"
 RDEPEND="${DEPEND}"
 IUSE=""
 
+# @FUNCTION: elisp_pkg_setup
+# @DESCRIPTION:
+# Test if the eselected Emacs version is sufficient to fulfil the major
+# version requirement of the NEED_EMACS variable.
+
 elisp_pkg_setup() {
 	local need_emacs=${NEED_EMACS:-21}
 	local have_emacs=$(elisp-emacs-version)
@@ -84,6 +89,12 @@ elisp_pkg_setup() {
 	einfo "Emacs version: ${have_emacs}"
 }
 
+# @FUNCTION: elisp_src_unpack
+# @DESCRIPTION:
+# Unpack the sources; also handle the case of a single *.el file in
+# WORKDIR for packages distributed that way.  For EAPIs without
+# src_prepare, call elisp_src_prepare.
+
 elisp_src_unpack() {
 	[ -n "${A}" ] && unpack ${A}
 	if [ -f ${P}.el ]; then
@@ -98,6 +109,11 @@ elisp_src_unpack() {
 	esac
 }
 
+# @FUNCTION: elisp_src_prepare
+# @DESCRIPTION:
+# Apply any patches listed in ELISP_PATCHES.  Patch files are searched
+# for in the current working dir, WORKDIR, and FILESDIR.
+
 elisp_src_prepare() {
 	local patch
 	for patch in ${ELISP_PATCHES}; do
@@ -113,8 +129,18 @@ elisp_src_prepare() {
 	done
 }
 
+# @FUNCTION: elisp_src_configure
+# @DESCRIPTION:
+# Do nothing, because Emacs packages seldomly bring a full build system.
+
 elisp_src_configure() { :; }
 
+# @FUNCTION: elisp_src_compile
+# @DESCRIPTION:
+# Call elisp-compile to byte-compile all Emacs Lisp (*.el) files.
+# If ELISP_TEXINFO lists any Texinfo sources, call makeinfo to generate
+# GNU Info files from then.
+
 elisp_src_compile() {
 	elisp-compile *.el || die
 	if [ -n "${ELISP_TEXINFO}" ]; then
@@ -122,6 +148,13 @@ elisp_src_compile() {
 	fi
 }
 
+# @FUNCTION: elisp_src_install
+# @DESCRIPTION:
+# Call elisp-install to install all Emacs Lisp (*.el and *.elc) files.
+# If the SITEFILE variable specifies a site-init file, install it with
+# elisp-site-file-install.  Also install any GNU Info files listed in
+# ELISP_TEXINFO and documentation listed in the DOCS variable.
+
 elisp_src_install() {
 	elisp-install ${PN} *.el *.elc || die
 	if [ -n "${SITEFILE}" ]; then
@@ -136,10 +169,20 @@ elisp_src_install() {
 	fi
 }
 
+# @FUNCTION: elisp_pkg_postinst
+# @DESCRIPTION:
+# Call elisp-site-regen, in order to collect the site initialisation for
+# all installed Emacs Lisp packages in the site-gentoo.el file.
+
 elisp_pkg_postinst() {
 	elisp-site-regen
 }
 
+# @FUNCTION: elisp_pkg_postrm
+# @DESCRIPTION:
+# Call elisp-site-regen, in order to collect the site initialisation for
+# all installed Emacs Lisp packages in the site-gentoo.el file.
+
 elisp_pkg_postrm() {
 	elisp-site-regen
 }