Cleanup and more doc'ification of php eclasses

1 files changed, 53 insertions, 26 deletions

diff --git a/eclass/php5_2-sapi.eclass b/eclass/php5_2-sapi.eclass
index 17c96df543a8..d97ae57b16b2 100644
--- a/eclass/php5_2-sapi.eclass
+++ b/eclass/php5_2-sapi.eclass
@@ -1,24 +1,24 @@
 # Copyright 1999-2007 Gentoo Foundation
 # Distributed under the terms of the GNU General Public License v2
-# $Header: /var/cvsroot/gentoo-x86/eclass/php5_2-sapi.eclass,v 1.11 2007/08/28 19:07:34 hoffie Exp $
+# $Header: /var/cvsroot/gentoo-x86/eclass/php5_2-sapi.eclass,v 1.12 2007/09/02 17:49:20 jokey Exp $
 
 # ========================================================================
+# Based on robbat2's work on the php4 sapi eclass
 #
-# php5_2-sapi.eclass
-#		Eclass for building different php5.2 SAPI instances
-#
-#		USE THIS ECLASS FOR THE "CONCENTRATED" PACKAGES
-#
-#		Based on robbat2's work on the php4 sapi eclass
-#
-# Author:	Stuart Herbert
-#			<stuart@gentoo.org>
-#
-# Author:	Luca Longinotti
-#			<chtekk@gentoo.org>
+# Author: Stuart Herbert <stuart@gentoo.org>
+# Author: Luca Longinotti <chtekk@gentoo.org>
 #
 # ========================================================================
 
+# @ECLASS: php5_2-sapi.eclass
+# @MAINTAINER:
+# Gentoo PHP team <php-bugs@gentoo.org>
+# @BLURB: Eclass for building different php-5.2 SAPI instances.
+# @DESCRIPTION:
+# Eclass for building different php-5.2 SAPI instances. Use it for the
+# new-style =dev-lang/php-5.2* ebuilds.
+
+
 PHPCONFUTILS_MISSING_DEPS="adabas birdstep db2 dbmaker empress empress-bcs esoob frontbase interbase msql oci8 sapdb solid sybase sybase-ct"
 
 WANT_AUTOCONF="latest"
@@ -26,14 +26,16 @@ WANT_AUTOMAKE="latest"
 
 inherit db-use flag-o-matic autotools toolchain-funcs libtool eutils phpconfutils php-common-r1
 
-# set MY_PHP_P in the ebuild
-
-# we only set these variables if we're building a copy of php which can be
-# installed as a package in its own right
-#
-# copies of php which are compiled into other packages (e.g. php support
-# for the thttpd web server) don't need these variables
+# @ECLASS-VARIABLE: MY_PHP_P
+# @DESCRIPTION:
+# Set MY_PHP_P in the ebuild as needed to match tarball version.
 
+# @ECLASS-VARIABLE: PHP_PACKAGE
+# @DESCRIPTION:
+# We only set this variable if we are building a copy of php which can be
+# installed as a package in its own.
+# Copies of php which are compiled into other packages (e.g. php support
+# for the thttpd web server) don't need this variable.
 if [[ "${PHP_PACKAGE}" == 1 ]] ; then
 	HOMEPAGE="http://www.php.net/"
 	LICENSE="PHP-3"
@@ -150,12 +152,18 @@ PHP_INI_UPSTREAM="php.ini-dist"
 
 # ========================================================================
 
-# PHP patchsets support
+# @ECLASS-VARIABLE: PHP_PATCHSET_REV
+# @DESCRIPTION:
+# Provides PHP patchsets support.
 SRC_URI="${SRC_URI} http://gentoo.longitekk.com/php-patchset-${MY_PHP_PV}-r${PHP_PATCHSET_REV}.tar.bz2"
 
-# Suhosin patch support
+# @ECLASS-VARIABLE: SUHOSIN_PATCH
+# @DESCRIPTION:
+# Tarball name for Suhosin patch (see http://www.suhosin.org/).
+# This feature will not be available in php if unset.
 [[ -n "${SUHOSIN_PATCH}" ]] && SRC_URI="${SRC_URI} suhosin? ( http://gentoo.longitekk.com/${SUHOSIN_PATCH} )"
 
+
 # ========================================================================
 
 EXPORT_FUNCTIONS pkg_setup src_compile src_install src_unpack pkg_postinst
@@ -308,17 +316,26 @@ php5_2-sapi_install_ini() {
 # EXPORTED FUNCTIONS
 # ========================================================================
 
+# @FUNCTION: php5_2-sapi_pkg_setup
+# @DESCRIPTION:
+# Performs all the USE flag testing and magic before we do anything else.
+# This way saves a lot of time.
 php5_2-sapi_pkg_setup() {
-	# let's do all the USE flag testing before we do anything else
-	# this way saves a lot of time
 	php5_2-sapi_check_use_flags
 }
 
+# @FUNCTION: php5_2-sapi_src_unpack
+# @DESCRIPTION:
+# Takes care of unpacking, patching and autotools magic and disables
+# interactive tests.
+
+# @VARIABLE: PHP_EXTRA_BRANDING
+# @DESCRIPTION:
+# This variable allows an ebuild to add additional information like
+# snapshot dates to the version line.
 php5_2-sapi_src_unpack() {
 	cd "${S}"
 
-	# This variable allows an ebuild to add additional information like
-	# snapshot dates to the version line
 	[[ -z "${PHP_EXTRA_BRANDING}" ]] && PHP_EXTRA_BRANDING=""
 
 	# Change PHP branding
@@ -393,6 +410,10 @@ php5_2-sapi_src_unpack() {
 	chmod 0755 configure || die "Failed to chmod configure to 0755"
 }
 
+# @FUNCTION: php5_2-sapi_src_compile
+# @DESCRIPTION:
+# Takes care of compiling php according to USE flags set by user (and those automagically
+# enabled via phpconfutils eclass if unavoidable).
 php5_2-sapi_src_compile() {
 	destdir=/usr/$(get_libdir)/php5
 
@@ -622,6 +643,9 @@ php5_2-sapi_src_compile() {
 	emake || die "make failed"
 }
 
+# @FUNCTION: php5_2-sapi_src_install
+# @DESCRIPTION:
+# Takes care of installing php (and its shared extensions if enabled).
 php5_2-sapi_src_install() {
 	destdir=/usr/$(get_libdir)/php5
 
@@ -675,6 +699,9 @@ php5_2-sapi_src_install() {
 	keepdir /usr/share/php5
 }
 
+# @FUNCTION: php5_2-sapi_pkg_postinst
+# @DESCRIPTION:
+# Provides important information to users after install is finished.
 php5_2-sapi_pkg_postinst() {
 	ewarn
 	ewarn "If you have additional third party PHP extensions (such as"