From b47b458048d87708a5591808feb83ab3c5a3198d Mon Sep 17 00:00:00 2001
From: Zac Medico <zmedico@gentoo.org>
Date: Mon, 17 Jul 2006 19:14:02 +0000
Subject: Add a docstring with epytext markup to portage_versions.pkgcmp(). 
 Thanks to chriswhite for this patch.

svn path=/main/trunk/; revision=3913
---
 pym/portage_versions.py | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

(limited to 'pym/portage_versions.py')

diff --git a/pym/portage_versions.py b/pym/portage_versions.py
index 43f45f2fc..7c5717987 100644
--- a/pym/portage_versions.py
+++ b/pym/portage_versions.py
@@ -123,6 +123,27 @@ def vercmp(ver1, ver2, silent=1):
 	return r1 - r2
 	
 def pkgcmp(pkg1, pkg2):
+	"""
+	Compare 2 package versions created in pkgsplit format.
+
+	Example usage:
+		>>> from portage_versions import *
+		>>> pkgcmp(pkgsplit('test-1.0-r1'),pkgsplit('test-1.2-r3'))
+		-1
+		>>> pkgcmp(pkgsplit('test-1.3'),pkgsplit('test-1.2-r3'))
+		1
+
+	@param pkg1: package to compare with
+	@type pkg1: list (example: ['test', '1.0', 'r1'])
+	@param pkg2: package to compare againts
+	@type pkg2: list (example: ['test', '1.0', 'r1'])
+	@rtype: None or integer
+	@return: 
+		1. None if package names are not the same
+		2. 1 if pkg1 is greater than pkg2
+		3. -1 if pkg1 is less than pkg2 
+		4. 0 if pkg1 equals pkg2
+	"""
 	if pkg1[0] != pkg2[0]:
 		return None
 	mycmp=vercmp(pkg1[1],pkg2[1])
-- 
cgit v1.2.3-1-g7c22