gnome2-live.eclass: use GNOME_ORG_MODULE for git URI, port to use eclass doc

1 files changed, 43 insertions, 12 deletions

diff --git a/eclass/gnome2-live.eclass b/eclass/gnome2-live.eclass
index 3a4dd6a3..0d158878 100644
--- a/eclass/gnome2-live.eclass
+++ b/eclass/gnome2-live.eclass
@@ -3,14 +3,16 @@
 # $Header: $
 
 #
-# gnome2-live.eclass
-#
+# @ECLASS: gnome2-live.eclass
+# @MAINTAINER:
+# gnome@gentoo.org
+# @AUTHOR:
+# Nirbheek Chauhan <nirbheek@gentoo.org>
+# @BLURB: Live ebuild phases for GNOME packages
+# @DESCRIPTION:
 # Exports additional functions used by live ebuilds written for GNOME packages
 # Always to be imported *AFTER* gnome2.eclass
 #
-# Author: Nirbheek Chauhan <nirbheek@gentoo.org>
-#
-
 
 inherit autotools gnome2 gnome2-utils libtool git-2
 
@@ -38,15 +40,28 @@ DEPEND="${DEPEND}
 # Extra options passed to elibtoolize
 ELTCONF=${ELTCONF:-}
 
-# Default git module name
-GNOME_LIVE_MODULE=${GNOME_LIVE_MODULE:-"${PN}"}
+# @ECLASS-VARIABLE: GNOME_LIVE_MODULE
+# @DESCRIPTION:
+# Default git module name is assumed to be the same as the gnome.org module name
+# used on ftp.gnome.org. We have GNOME_ORG_MODULE because we inherit gnome.org
+: ${GNOME_LIVE_MODULE:="${GNOME_ORG_MODULE}"}
 
-# GIT URI for the project
-EGIT_REPO_URI="${EGIT_REPO_URI:-"git://git.gnome.org/${GNOME_LIVE_MODULE}"}"
+# @ECLASS-VARIABLE: EGIT_REPO_URI
+# @DESCRIPTION:
+# git URI for the project, uses GNOME_LIVE_MODULE by default
+: "${EGIT_REPO_URI:="git://git.gnome.org/${GNOME_LIVE_MODULE}"}"
+
+# @ECLASS-VARIABLE: PATCHES
+# @DESCRIPTION:
+# Whitespace-separated list of patches to apply after cloning
+: ${PATCHES:=""}
 
 # Unset SRC_URI auto-set by gnome2.eclass
 SRC_URI=""
 
+# @FUNCTION: gnome2-live_get_var
+# @DESCRIPTION:
+# Get macro variable values from configure.ac, etc
 gnome2-live_get_var() {
 	local var f
 	var="$1"
@@ -54,6 +69,10 @@ gnome2-live_get_var() {
 	echo $(sed -ne "s/${var}(\(.*\))/\1/p" "${f}" | tr -d '[]')
 }
 
+# @FUNCTION: gnome2-live_get_var
+# @DESCRIPTION:
+# Calls git-2_src_unpack, and unpacks ${A} if required.
+# Also calls gnome2-live_src_prepare for older EAPI.
 gnome2-live_src_unpack() {
 	if test -n "${A}"; then
 		unpack ${A}
@@ -62,9 +81,15 @@ gnome2-live_src_unpack() {
 	has src_prepare ${EXPORTED_FUNCTIONS} || gnome2-live_src_prepare
 }
 
+# @FUNCTION: gnome2-live_src_prepare
+# @DESCRIPTION:
+# Lots of magic to workaround autogen.sh quirks in various packages
+# Creates blank ChangeLog and necessary macro dirs. Runs various autotools
+# programs if required, and finally runs eautoreconf.
 gnome2-live_src_prepare() {
 	# Blame git.eclass
 	cd "${S}"
+
 	for i in ${PATCHES}; do
 		epatch "${i}"
 	done
@@ -141,17 +166,23 @@ gnome2-live_src_prepare() {
 	elibtoolize ${ELTCONF}
 }
 
-# So that it replaces gnome2_src_unpack in ebuilds that call it
+# @FUNCTION: gnome2_src_unpack
+# @DESCRIPTION:
+# Defined so that it replaces gnome2_src_unpack in ebuilds that call it
 gnome2_src_unpack() {
 	gnome2-live_src_unpack
 }
 
-# So that it replaces gnome2_src_prepare in ebuilds that call it
+# @FUNCTION: gnome2_src_prepare
+# @DESCRIPTION:
+# Defined so that it replaces gnome2_src_prepare in ebuilds that call it
 gnome2_src_prepare() {
 	gnome2-live_src_prepare
 }
 
-# Run manually for ebuilds that have a custom pkg_postinst
+# @FUNCTION: gnome2-live_pkg_postinst
+# @DESCRIPTION:
+# Must be run manually for ebuilds that have a custom pkg_postinst
 gnome2-live_pkg_postinst() {
 	ewarn "This is a live ebuild, upstream trunks will mostly be UNstable"
 	ewarn "Do NOT report bugs about this package to Gentoo"