Improve docs.

8 files changed, 120 insertions, 17 deletions

diff --git a/pmstestsuite/library/case.py b/pmstestsuite/library/case.py
index 00a6cd4..a5817fb 100644
--- a/pmstestsuite/library/case.py
+++ b/pmstestsuite/library/case.py
@@ -58,42 +58,92 @@ def cleanup_test_case_name(classname):
 	return pn_re.sub('\\1-\\2', classname).lower()
 
 class AssertionResult(ABCObject, BoolCompat):
+	"""
+	Base class for assertion results.
+	"""
+
 	def __init__(self, name):
 		self._name = name
 		self._undefined = False
 
 	@property
 	def name(self):
+		"""
+		The assertion name.
+
+		@type: str
+		"""
 		return self._name
 
 	@property
 	def prefix(self):
+		"""
+		The assertion name prefix.
+
+		@type: str
+		"""
 		return None
 
 	@property
 	def unprefixed_name(self):
+		"""
+		The assertion name without prefix.
+
+		@type: str
+		"""
 		return self.name
 
 	@property
 	def undefined(self):
+		"""
+		Whether the assertion has undefined result.
+
+		@type: bool
+		"""
 		return self._undefined
 
 	@abstractproperty
 	def expected(self):
+		"""
+		Expected value.
+
+		@type: any
+		"""
 		pass
 
 	@abstractproperty
 	def actual(self):
+		"""
+		Actual value.
+
+		@type: any
+		"""
 		pass
 
 	@abstractmethod
 	def __bool__(self):
+		"""
+		Check whether the assertion succeeds.
+
+		@return: whether the assertion matches
+		@rtype: bool
+		"""
 		pass
 
 	def __str__(self):
+		"""
+		Return the stringified assertion description.
+
+		@return: stringified assertion
+		@rtype: str
+		"""
 		return '%s == %s' % (self.actual, self.expected)
 
 class BoolAssertionResult(AssertionResult):
+	"""
+	Assertion for a boolean match.
+	"""
+
 	def __init__(self, name, expect, cond):
 		AssertionResult.__init__(self, name)
 		self._expect = bool(expect)
@@ -113,6 +163,10 @@ class BoolAssertionResult(AssertionResult):
 		return self._expect == self._cond
 
 class ContainsAssertionResult(AssertionResult):
+	"""
+	Assertion checking whether a value is on the list.
+	"""
+
 	def __init__(self, name, needle, container):
 		AssertionResult.__init__(self, name)
 		self._cont = container
@@ -135,6 +189,10 @@ class ContainsAssertionResult(AssertionResult):
 		return self._need in self._cont
 
 class EqualAssertionResult(AssertionResult):
+	"""
+	Assertion checking universal equality.
+	"""
+
 	def __init__(self, name, expect, value):
 		AssertionResult.__init__(self, name)
 		self._expect = expect
@@ -152,6 +210,10 @@ class EqualAssertionResult(AssertionResult):
 		return self._expect == self._value
 
 class NotEqualAssertionResult(EqualAssertionResult):
+	"""
+	Assertion checking universal non-equality.
+	"""
+
 	def __bool__(self):
 		if self._value is None:
 			return False
@@ -322,8 +384,8 @@ class TestCase(ABCObject):
 
 		@param value: the actual value
 		@type value: any
-		@param expect: the unallowed value
-		@type expect: any
+		@param unallowed: the unallowed value
+		@type unallowed: any
 		@param msg: assertion description
 		@type msg: string
 		@param undefined: whether the result is undefined
@@ -463,7 +525,7 @@ class EbuildTestCase(TestCase):
 		return 'pms-test/%s' % self.p
 
 	def atom(self, pm):
-		""" Return atom for the test. """
+		""" Return an exact-match atom for the test. """
 		return pm.Atom('=%s' % self.cpv)
 
 	def _finalize(self):
@@ -501,12 +563,22 @@ class EbuildTestCase(TestCase):
 		class EbuildTestCaseEbuildFile(object):
 			""" Lazy ebuild contents evaluator for EbuildTestCase. """
 			def __init__(self, parent):
-				""" Instantiate the evaluator for test case <parent>. """
+				"""
+				Instantiate the evaluator for test case.
+
+				@param parent: relevant test case
+				@type parent: L{EbuildTestCase}
+				"""
 				assert(isinstance(parent, EbuildTestCase))
 				self._parent = parent
 
 			def __str__(self):
-				""" Return the ebuild contents as string. """
+				"""
+				Return the ebuild contents as string.
+
+				@return: ebuild contents
+				@rtype: str
+				"""
 				contents = [ebuild_header % (self._parent.eapi,
 					' '.join(['pms-test'] + self._parent.inherits))]
 
@@ -542,6 +614,9 @@ class EbuildTestCase(TestCase):
 		"""
 		Check the correctness of the result of test execution. By default,
 		checks whether the ebuild was actually merged.
+
+		@param pm: the package manager instance
+		@type pm: L{PackageManager}
 		"""
 
 		merged = self.atom(pm) in pm.installed
diff --git a/pmstestsuite/library/depend_case.py b/pmstestsuite/library/depend_case.py
index fb2881b..bc06aa3 100644
--- a/pmstestsuite/library/depend_case.py
+++ b/pmstestsuite/library/depend_case.py
@@ -6,6 +6,12 @@ from .case import EbuildTestCase, AssertionResult
 from .eclass_case import EclassTestCase
 
 class DepWrappedAssertion(AssertionResult):
+	"""
+	Assertion which have occured in a dependency ebuild.
+
+	It basically wraps the original assertion, adding a prefix.
+	"""
+
 	def __init__(self, assertion, prefix):
 		self._assert = assertion
 		self._prefix = prefix
diff --git a/pmstestsuite/library/standard/dbus_case.py b/pmstestsuite/library/standard/dbus_case.py
index a76bba4..6bfbd88 100644
--- a/pmstestsuite/library/standard/dbus_case.py
+++ b/pmstestsuite/library/standard/dbus_case.py
@@ -52,7 +52,10 @@ class RunningTest(dbus.service.Object):
 
 	def __init__(self, test):
 		"""
-		Initialize the D-Bus object for test <test>.
+		Initialize the D-Bus object for the test.
+
+		@param test: the test
+		@type test: L{TestCase}
 		"""
 		self.test = test
 		self.reset()
@@ -73,14 +76,21 @@ class RunningTest(dbus.service.Object):
 			dbus_interface=dbus_interface_name,
 			in_signature='', out_signature='')
 	def test_started(self):
-		""" Notify the test suite that a particular test has been started. """
+		"""
+		Notify the test suite that a particular test has been started.
+		"""
 		self.test.dbus_started = True
 
 	@dbus.service.method(
 			dbus_interface=dbus_interface_name,
 			in_signature='s', out_signature='')
 	def append_output(self, l):
-		""" Append the line <l> to the test output. """
+		"""
+		Append the string to the test output.
+
+		@param l: result string
+		@type l: C{dbus.UTF8String}
+		"""
 		self.test.dbus_output.append(str(l))
 
 class DBusBaseTestCase(object):
@@ -92,19 +102,27 @@ class DBusBaseTestCase(object):
 		self._dbusobj = RunningTest(self)
 
 	def _finalize(self):
-		""" Finalize the object, ensuring pkg_setup() will be called. """
+		"""
+		Finalize the object, ensuring that C{pkg_setup()} will be called.
+		"""
 		if self.phase_funcs['pkg_setup']:
 			self.phase_funcs['pkg_setup'].insert(0, 'pms-test-dbus_pkg_setup')
 
 	def check_dbus_result(self, output, pm):
 		"""
-		Check whether the <output> sent through D-Bus matches expected test
+		Check whether the output sent through D-Bus matches expected test
 		output.
 
-		Return True if it does, False otherwise.
-
 		The default implementation simply checks whether the test was merged
-		alike EbuildTestCase.check_result().
+		alike L{EbuildTestCase.check_result()}.
+
+		@param output: the D-Bus output
+		@type output: list(str)
+		@param pm: the package manager instance
+		@type pm: L{PackageManager}
+		@return: C{True} if output matches expected test result, C{False}
+			otherwise
+		@rtype: bool
 		"""
 		pass
 
@@ -118,7 +136,7 @@ class DBusBaseTestCase(object):
 		self.check_dbus_result(self._pop_dbus_output(), pm)
 
 class DBusEbuildTestCase(DBusBaseTestCase, EbuildTestCase):
-	""" D-Bus capable base test case. """
+	""" D-Bus capable ebuild test case. """
 
 	def __init__(self, *args, **kwargs):
 		""" Initialize the test case and the D-Bus object for it. """
diff --git a/pmstestsuite/library/standard/ext_cases.py b/pmstestsuite/library/standard/ext_cases.py
index 9f0bbf6..94a93cc 100644
--- a/pmstestsuite/library/standard/ext_cases.py
+++ b/pmstestsuite/library/standard/ext_cases.py
@@ -7,7 +7,7 @@ from .dbus_case import DBusEbuildTestCase
 class DBusFetchingEbuildTestCase(DBusEbuildTestCase):
 	"""
 	A DBusEbuildTestCase variant with a standarized way of fetching
-	sources -- to decrease ${DISTDIR} pollution.
+	sources -- to decrease {${DISTDIR}} pollution.
 	"""
 
 	def __init__(self, *args, **kwargs):
diff --git a/pmstestsuite/library/standard/workdir_fallback.py b/pmstestsuite/library/standard/workdir_fallback.py
index 6c96abe..04ce281 100644
--- a/pmstestsuite/library/standard/workdir_fallback.py
+++ b/pmstestsuite/library/standard/workdir_fallback.py
@@ -19,7 +19,7 @@ class WorkdirFallbackTest(DBusFetchingEbuildTestCase):
 	}
 	phase_funcs = {
 		'src_unpack': [
-			'echo $A'
+			'echo ${A}'
 		],
 		'src_compile': [
 			':'
diff --git a/pmstestsuite/output/cli.py b/pmstestsuite/output/cli.py
index c11e0be..d07fbfa 100644
--- a/pmstestsuite/output/cli.py
+++ b/pmstestsuite/output/cli.py
@@ -5,6 +5,8 @@
 from . import OutputModule
 
 class CLIOutput(OutputModule):
+	""" Command-line output module. """
+
 	name = 'cli'
 
 	def __call__(self, allresults, verbose = False):
diff --git a/pmstestsuite/output/html.py b/pmstestsuite/output/html.py
index 1e497b1..71ea2ac 100644
--- a/pmstestsuite/output/html.py
+++ b/pmstestsuite/output/html.py
@@ -9,6 +9,8 @@ from abc import abstractmethod
 from . import OutputModule
 
 class HTMLOutput(OutputModule):
+	""" HTML output module. """
+
 	name = 'html'
 
 	def __init__(self, path = None):
diff --git a/pmstestsuite/pm/paludispm.py b/pmstestsuite/pm/paludispm.py
index 3fbcfee..a77a7bc 100644
--- a/pmstestsuite/pm/paludispm.py
+++ b/pmstestsuite/pm/paludispm.py
@@ -17,7 +17,7 @@ class PaludisPM(_PaludisPM, PackageManager):
 	"""
 	A class implementing the interfaces to the Paludis PM.
 
-	Requires Paludis with USE=python.
+	Requires Paludis with C{USE=python}.
 	"""
 	name = 'paludis'