[gentoo-python] Eclass doc improvements for python-utils-r1.eclass

[gentoo-python] Eclass doc improvements for python-utils-r1.eclass

[Mike Gilbert]

[-- Attachment #1: Type: text/plain, Size: 106 bytes --]

Attached patch expands on EPYTHON and PYTHON descriptions, and cleans
up some eclass-to-manpage warnings.

[-- Attachment #2: python-utils-r1.patch --]
[-- Type: application/octet-stream, Size: 2994 bytes --]

Index: python-utils-r1.eclass
===================================================================
RCS file: /var/cvsroot/gentoo-x86/eclass/python-utils-r1.eclass,v
retrieving revision 1.26
diff -u -r1.26 python-utils-r1.eclass
--- python-utils-r1.eclass	31 May 2013 17:50:33 -0000	1.26
+++ python-utils-r1.eclass	1 Jun 2013 18:02:38 -0000
@@ -79,10 +79,18 @@
 }
 
 # @ECLASS-VARIABLE: PYTHON
+# @DEFAULT_UNSET
 # @DESCRIPTION:
 # The absolute path to the current Python interpreter.
 #
-# Set and exported only in commands run by python_foreach_impl().
+# This variable is set automatically in the following contexts:
+#
+# python-r1: Set in functions called by python_foreach_impl() or after
+# calling python_export_best().
+#
+# python-single-r1: Set after calling python-single-r1_pkg_setup().
+#
+# distutils-r1: Set within any of the python sub-phase functions.
 #
 # Example value:
 # @CODE
@@ -90,12 +98,18 @@
 # @CODE
 
 # @ECLASS-VARIABLE: EPYTHON
+# @DEFAULT_UNSET
 # @DESCRIPTION:
 # The executable name of the current Python interpreter.
 #
-# This variable is used consistently with python.eclass.
+# This variable is set automatically in the following contexts:
 #
-# Set and exported only in commands run by python_foreach_impl().
+# python-r1: Set in functions called by python_foreach_impl() or after
+# calling python_export_best().
+#
+# python-single-r1: Set after calling python-single-r1_pkg_setup().
+#
+# distutils-r1: Set within any of the python sub-phase functions.
 #
 # Example value:
 # @CODE
@@ -103,6 +117,7 @@
 # @CODE
 
 # @ECLASS-VARIABLE: PYTHON_SITEDIR
+# @DEFAULT_UNSET
 # @DESCRIPTION:
 # The path to Python site-packages directory.
 #
@@ -114,6 +129,7 @@
 # @CODE
 
 # @ECLASS-VARIABLE: PYTHON_INCLUDEDIR
+# @DEFAULT_UNSET
 # @DESCRIPTION:
 # The path to Python include directory.
 #
@@ -125,6 +141,7 @@
 # @CODE
 
 # @ECLASS-VARIABLE: PYTHON_LIBPATH
+# @DEFAULT_UNSET
 # @DESCRIPTION:
 # The path to Python library.
 #
@@ -137,6 +154,7 @@
 # @CODE
 
 # @ECLASS-VARIABLE: PYTHON_CFLAGS
+# @DEFAULT_UNSET
 # @DESCRIPTION:
 # Proper C compiler flags for building against Python. Obtained from
 # pkg-config or python-config.
@@ -151,6 +169,7 @@
 # @CODE
 
 # @ECLASS-VARIABLE: PYTHON_LIBS
+# @DEFAULT_UNSET
 # @DESCRIPTION:
 # Proper C compiler flags for linking against Python. Obtained from
 # pkg-config or python-config.
@@ -165,6 +184,7 @@
 # @CODE
 
 # @ECLASS-VARIABLE: PYTHON_PKG_DEP
+# @DEFAULT_UNSET
 # @DESCRIPTION:
 # The complete dependency on a particular Python package as a string.
 #
@@ -456,8 +476,8 @@
 }
 
 # @FUNCTION: _python_rewrite_shebang
-# @INTERNAL
 # @USAGE: [<EPYTHON>] <path>...
+# @INTERNAL
 # @DESCRIPTION:
 # Replaces 'python' executable in the shebang with the executable name
 # of the specified interpreter. If no EPYTHON value (implementation) is
@@ -526,8 +546,8 @@
 }
 
 # @FUNCTION: _python_ln_rel
-# @INTERNAL
 # @USAGE: <from> <to>
+# @INTERNAL
 # @DESCRIPTION:
 # Create a relative symlink.
 _python_ln_rel() {