Reformat docs for epydoc.

3 files changed, 112 insertions, 48 deletions

diff --git a/pmstestsuite/library/__init__.py b/pmstestsuite/library/__init__.py
index d65958f..c286d22 100644
--- a/pmstestsuite/library/__init__.py
+++ b/pmstestsuite/library/__init__.py
@@ -19,21 +19,38 @@
 '# Copyright 1999...inherit pms-test...die...'
 """
 
+from abc import abstractproperty
+from gentoopm.util import ABCObject
+
 from pmstestsuite.library.case import TestCase
 
-class TestLibrary(object):
-	""" Base class for a test library. """
+class TestLibrary(ABCObject):
+	"""
+	Base class for a test library.
+	
+	@ivar tests: cache of instantiated tests
+	@type tests: list(L{TestCase})
+	"""
 
 	tests = None
+	
+	@abstractproperty
+	def test_names(self):
+		"""
+		Names of test classes in the library, including a module path relative
+		to the library root.
+
+		@type: iterable(string)
+		"""
 
 	def __iter__(self):
 		"""
 		Iterate over all the tests in a test library, loading its modules
-		as necessary. Uses <self.test_names> to get the module names.
+		as necessary.
 
-		Returns an iterator over TestCase subclass instances or raises one
-		of the following exceptions:
-		- ImportError if submodule import fails.
+		@return: an iterable over instantiated test cases
+		@rtype: generator(L{TestCase})
+		@raise ImportError: if submodule import fails.
 		"""
 
 		if self.tests is not None:
@@ -87,13 +104,16 @@ class TestLibrary(object):
 
 def load_library(name, **kwargs):
 	"""
-	Try to load a test library <name>. Instiantiate the first TestLibrary
-	subclass found there. Pass kwargs to the __init__() function.
-
-	Returns a new TestLibrary subclass instance or raises one of the following
-	exceptions:
-	- ImportError if module import fails,
-	- TypeError if no matching class is found.
+	Try to load a test library. Instiantiate the first TestLibrary subclass
+	found there.
+
+	@param name: the test library name
+	@type name: string
+	@param kwargs: keyword arguments to pass to the library constructor
+	@return: an instantiated test library
+	@rtype: L{TestLibrary}
+	@raise ImportError: if module import fails
+	@raise TypeError: if no matching class is found in the module
 	"""
 
 	modname = 'pmstestsuite.library.%s' % name
diff --git a/pmstestsuite/library/case.py b/pmstestsuite/library/case.py
index 4d5d8fe..18490ec 100644
--- a/pmstestsuite/library/case.py
+++ b/pmstestsuite/library/case.py
@@ -3,6 +3,7 @@
 # Released under the terms of the 2-clause BSD license.
 
 import copy, random, re
+from gentoopm.util import ABCObject
 
 from abc import ABCMeta, abstractmethod, abstractproperty
 
@@ -13,6 +14,8 @@ phase_func_names = [
 	'pkg_preinst', 'pkg_postinst'
 ]
 
+""" Names of all phase functions supported in EAPIs. """
+
 ebuild_header = '''# Copyright 1999-2011 Gentoo Foundation
 # Distributed under the terms of the GNU General Public License v2
 # $Header: $
@@ -23,11 +26,13 @@ inherit %s
 
 '''
 
+""" A common ebuild header. """
+
 pn_re = re.compile('([^A-Z])([A-Z])')
 
 def cleanup_test_case_name(classname):
 	"""
-	Create the ebuild PN from <classname>.
+	Create the ebuild PN from classname.
 
 	>>> cleanup_test_case_name('Testzor')
 	'testzor'
@@ -39,15 +44,23 @@ def cleanup_test_case_name(classname):
 	'very-random-camel-case'
 	>>> cleanup_test_case_name('RDependTest')
 	'rdepend'
+
+	@param classname: the class name to clean up
+	@type classname: string
 	"""
 
 	if classname.endswith('Test'):
 		classname = classname[:-4]
 	return pn_re.sub('\\1-\\2', classname).lower()
 
-class TestCase(object):
-	""" Base class for a test case. """
-	__metaclass__ = ABCMeta
+class TestCase(ABCObject):
+	"""
+	Base class for a test case.
+	
+	@ivar _finalized: has the case initialization been finished yet?
+		Set by L{_finalize()}.
+	@type _finalized: bool
+	"""
 
 	_finalized = False
 
@@ -62,23 +75,30 @@ class TestCase(object):
 	def get_output_files(self):
 		"""
 		Get a dict of files to output in the repository for the test case.
-		
-		Returns a dict with keys being filenames relative to the repository root
-		and associated values evaluating to a file contents (as strings).
+
+		@return: a dict where keys are file paths (relative to the repository
+			root), and values evaluate to file contents
+		@rtype: dict (string -> stringifiable)
 		"""
 		pass
 
 	@abstractmethod
 	def clean(self, pm):
 		"""
-		Schedule cleaning the test using PackageManager instance <pm>.
+		Schedule cleaning the test.
+
+		@param pm: the package manager instance
+		@type pm: L{PackageManager}
 		"""
 		pass
 
 	@abstractmethod
 	def start(self, pm):
 		"""
-		Schedule starting the test using PackageManager instance <pm>.
+		Schedule starting the test.
+
+		@param pm: the package manager instance
+		@type pm: L{PackageManager}
 		"""
 		pass
 
@@ -86,27 +106,32 @@ class TestCase(object):
 	def check_result(self, pm):
 		"""
 		Check the correctness of the result of test execution.
-		<pm> points to the current PackageManager instance.
 
-		Shall return True if the results indicate that the test succeeded,
-		False otherwise.
+		@param pm: the package manager instance
+		@type pm: L{PackageManager}
+
+		@return: True if the test succeeded, False otherwise
+		@rtype: bool
 		"""
 		pass
 
 class EbuildTestCase(TestCase):
 	"""
 	Test case using a single ebuild (per EAPI).
+
+	The __init__() function is going to clone (deepcopy()) all the instance
+	variables to allow modifying them easily.
 	
-	Properties:
-	- ebuild_vars - additional global variables (a dict of strings),
-	- expect_failure - if set to False (the default), the test is supposed
+	@ivar ebuild_vars: additional global variables
+	@type ebuild_vars: dict (string -> string)
+	@ivar expect_failure: if set to False (the default), the test is supposed
 		to merge successfully. Otherwise, the test ebuild is supposed to fail
-		to merge (die),
-	- inherits - additional eclasses to inherit (a list of strings),
-	- phase_funcs - phase function contents (a dict of lists).
-
-	The __init__() function is going to clone (deepcopy()) all the above
-	properties to allow modifying instance variables easily.
+		to merge (die)
+	@type expect_failure: bool
+	@ivar inherits: additional eclasses to inherit
+	@type inherits: list (string)
+	@ivar phase_funcs: phase function contents
+	@type phase_funcs: dict (string -> list(string))
 	"""
 
 	ebuild_vars = {}
@@ -119,6 +144,11 @@ class EbuildTestCase(TestCase):
 		"""
 		Evaluate and return the value of a property when passed a property
 		object, or return the passed value otherwise.
+
+		@param prop_or_obj: the object to process
+		@type prop_or_obj: property/object
+		@return: value of the property
+		@rtype: object
 		"""
 
 		if isinstance(prop_or_obj, property):
@@ -134,6 +164,8 @@ class EbuildTestCase(TestCase):
 
 		For example, if a feature is required in EAPI 3+ and optional
 		in earlier EAPIs, this variable should contain (3,4).
+
+		@type: iterable
 		"""
 		return (0, 1, 2, 3, 4)
 
@@ -145,6 +177,8 @@ class EbuildTestCase(TestCase):
 		a change of behaviour occurs.
 
 		When unset, defaults to a random element of .supported_eapis().
+
+		@type: iterable
 		"""
 		return (random.choice(cls._eval_prop(cls.supported_eapis)),)
 
@@ -154,7 +188,8 @@ class EbuildTestCase(TestCase):
 		Instantiate the test case for all relevant EAPIs. If in thorough
 		mode, assume all supported EAPIs are relevant.
 
-		Returns an iterator over a list of test case instances.
+		@return: an iterable over test case instances
+		@rtype: generator(L{EbuildTestCase})
 		"""
 
 		if thorough:
@@ -202,7 +237,12 @@ class EbuildTestCase(TestCase):
 		return '%s (%s)' % (self.p, self._stripped_docstring)
 
 	def __init__(self, eapi):
-		""" Instiantate the test case for a particular EAPI. """
+		"""
+		Instiantate the test case for a particular EAPI.
+		
+		@param eapi: the EAPI
+		@type eapi: string
+		"""
 		self.eapi = eapi
 
 		for v in ('ebuild_vars', 'inherits', 'phase_funcs'):
@@ -216,12 +256,6 @@ class EbuildTestCase(TestCase):
 				'm68k ~mips ppc ppc64 s390 sh sparc x86'
 
 	def get_output_files(self):
-		"""
-		Get a dict of files to output in the repository for the test case.
-		
-		Returns a dict with keys being filenames relative to the repository root
-		and associated values being classes evaluating to the file contents.
-		"""
 		class EbuildTestCaseEbuildFile(object):
 			""" Lazy ebuild contents evaluator for EbuildTestCase. """
 			def __init__(self, parent):
@@ -266,9 +300,6 @@ class EbuildTestCase(TestCase):
 		"""
 		Check the correctness of the result of test execution. By default,
 		checks whether the ebuild was actually merged.
-
-		Returns True if the results indicate that the test succeeded, False
-		otherwise.
 		"""
 
 		merged = self.atom(pm) in pm.installed
diff --git a/pmstestsuite/library/depend_case.py b/pmstestsuite/library/depend_case.py
index a9a34f6..6a6afc3 100644
--- a/pmstestsuite/library/depend_case.py
+++ b/pmstestsuite/library/depend_case.py
@@ -10,13 +10,21 @@ class EbuildDependencyTestCase(EbuildTestCase):
 	resolution.
 
 	In order to perform a dependency test, please:
-	1) create EbuildTestCase subclasses for the dependencies like usual,
-	2) create EbuildDependencyTestCase and refer to the classes created above in
-		depend_classes or rdepend_classes.
+
+		1. create EbuildTestCase subclasses for the dependencies like usual,
+		2. create EbuildDependencyTestCase and refer to the classes created
+		above in depend_classes or rdepend_classes.
 
 	The class is going to set up all ebuilds, DEPEND and RDEPEND automagically.
 	However, you need to provide phase functions to perform the actual
 	dependency test (i.e. check whether the dependency was merged successfully).
+
+	@cvar depend_classes: classes for DEPEND generation
+	@type depend_classes: iterable(L{EbuildTestCase})
+	@cvar rdepend_classes: classes for RDEPEND generation
+	@type rdepend_classes: iterable(L{EbuildTestCase})
+	@cvar pdepend_classes: classes for PDEPEND generation
+	@type pdepend_classes: iterable(L{EbuildTestCase})
 	"""
 
 	depend_classes = []
@@ -24,6 +32,11 @@ class EbuildDependencyTestCase(EbuildTestCase):
 	pdepend_classes = []
 
 	def __init__(self, eapi):
+		"""
+		Instantiate the dependency test case and dependant sub-cases. Set
+		C{DEPEND}, C{RDEPEND} and C{PDEPEND}.
+		"""
+
 		EbuildTestCase.__init__(self, eapi)
 
 		self.dependant_ebuilds = []