[gentoo-commits] proj/gentoopm:master commit in: gentoopm/

["Michał Górny" <mgorny@gentoo.org>]

commit:     53efdd7a7b7317b8baa1d86cdbad55f1a303d488
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Jul 10 11:22:44 2011 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Sun Jul 10 11:22:44 2011 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/gentoopm.git;a=commit;h=53efdd7a

Re-doc core code.

---
 gentoopm/__init__.py    |   13 +++++++++++--
 gentoopm/preferences.py |    3 +++
 gentoopm/querycli.py    |   18 ++++++++++++++++++
 gentoopm/submodules.py  |   26 ++++++++++++++++----------
 4 files changed, 48 insertions(+), 12 deletions(-)

diff --git a/gentoopm/__init__.py b/gentoopm/__init__.py
index f05d6ec..8fc5b3f 100644
--- a/gentoopm/__init__.py
+++ b/gentoopm/__init__.py
@@ -5,11 +5,20 @@
 
 PV = '0'
 
+"""
+The package version.
+
+@type: string
+"""
+
 def get_package_manager():
 	"""
 	Get the PackageManager instance for the best package manager available.
-	Takes user preferences into consideration. Raises an exception if no PM
-	could be found.
+	Takes user preferences into consideration.
+
+	@return: Best package manager instance available
+	@rtype: L{PackageManager}
+	@raise Exception: No package manager could be imported.
 	"""
 
 	from gentoopm.preferences import get_preferred_pms

diff --git a/gentoopm/preferences.py b/gentoopm/preferences.py
index c33f744..7141c6d 100644
--- a/gentoopm/preferences.py
+++ b/gentoopm/preferences.py
@@ -13,6 +13,9 @@ def get_preferred_pms():
 	"""
 	Find out what are the user's PM preferences and return the preferred PM
 	names as an iterable, with the most preferred one coming first.
+
+	@return: Preferred PMs, in order
+	@rtype: iterable(string)
 	"""
 
 	ret = []

diff --git a/gentoopm/querycli.py b/gentoopm/querycli.py
index 9267c4e..e1ea091 100644
--- a/gentoopm/querycli.py
+++ b/gentoopm/querycli.py
@@ -13,6 +13,11 @@ def reponame(val):
 	"""
 	Check the value for correctness as repository name. In fact, it only ensures
 	it isn't a path so that it won't confuse pm.repositories[val].
+
+	@param val: the config option value
+	@type val: string
+	@return: whether the value is a correct repo name
+	@rtype: bool
 	"""
 	if os.path.isabs(val):
 		raise ValueError('Invalid repository name: %s' % val)
@@ -25,6 +30,9 @@ class PMQueryCommand(ABCObject):
 	def help(self):
 		"""
 		Return the help string for a sub-command.
+
+		@return: the help string
+		@rtype: string
 		"""
 		descdoc = ' '.join(self.__doc__.split())
 		descdoc = descdoc[0].lower() + descdoc[1:]
@@ -33,6 +41,9 @@ class PMQueryCommand(ABCObject):
 	def __init__(self, argparser):
 		"""
 		Instantiate the subcommand, setting argument parser as necessary.
+
+		@param argparser: sub-command argument parser
+		@type argparser: C{argparse.ArgumentParser}
 		"""
 		argparser.set_defaults(instance = self)
 		self._arg = argparser
@@ -43,6 +54,13 @@ class PMQueryCommand(ABCObject):
 		Call the sub-command, passing pm (a working PackageManager instance)
 		and args (the result of argument parsing). Can return exit code
 		for the process if relevant. If it doesn't, 0 will be used.
+
+		@param pm: package manager instance
+		@type pm: L{PackageManager}
+		@param args: command arguments
+		@type args: C{argparse.Namespace}
+		@return: Process exit code or None if irrelevant
+		@rtype: bool/None
 		"""
 		pass
 

diff --git a/gentoopm/submodules.py b/gentoopm/submodules.py
index 7659361..82945bf 100644
--- a/gentoopm/submodules.py
+++ b/gentoopm/submodules.py
@@ -11,14 +11,15 @@ supported_pms = {
 
 def get_pm(pm_name):
 	"""
-	Get the PackageManager instance for a particularly named PM. Either returns
-	a PackageManager subclass instance or raises one of the following
-	exceptions:
-
-	- KeyError if pm_name doesn't refer to a supported PM,
-	- ImportError if modules required for a particular PM are not available,
-	- NameError if for some reason required class isn't provided by the module
-		(consider this an internal error).
+	Get the PackageManager instance for a particularly named PM.
+
+	@param pm_name: name of package manager to use
+	@type pm_name: string
+	@return: A package manager instance
+	@rtype: L{PackageManager}
+	@raise KeyError: pm_name doesn't refer to a supported PM
+	@raise ImportError: modules required for the PM are not available
+	@raise NameError: PM class is not available
 	"""
 
 	modname, clsname = supported_pms[pm_name]
@@ -28,8 +29,13 @@ def get_pm(pm_name):
 def get_any_pm(pm_list):
 	"""
 	Get the first working PackageManager from the pm_list. This function will
-	try to import them in order and either return the first succeeding or raise
-	an exception if all of them fail.
+	try to import them in order and return the first succeeding.
+
+	@param pm_list: list of preferred package manager names, in order
+	@type pm_list: iterable(string)
+	@return: Best available package manager instance
+	@rtype: L{PackageManager}
+	@raise Exception: if none of the PMs are available
 	"""
 
 	for pm_name in pm_list: