doc updates

1 files changed, 75 insertions, 17 deletions

diff --git a/pym/portage_core.py b/pym/portage_core.py
index ad5b6e9..0dd901e 100644
--- a/pym/portage_core.py
+++ b/pym/portage_core.py
@@ -1,14 +1,82 @@
 # Copyright 1999-200 Gentoo Technologies, Inc. 
 # Distributed under the terms of the GNU General Public License, v2 or later 
 # Author: Daniel Robbins <drobbins@gentoo.org>
-# $Header: /local/data/ulm/cvs/history/var/cvsroot/gentoo-src/portage/pym/Attic/portage_core.py,v 1.2 2001/11/06 23:39:13 drobbins Exp $
+# $Header: /local/data/ulm/cvs/history/var/cvsroot/gentoo-src/portage/pym/Attic/portage_core.py,v 1.3 2001/11/07 04:41:04 drobbins Exp $
 
 import string
 
 endversion={"pre":-2,"p":0,"alpha":-4,"beta":-3,"rc":-1}
 
+""" 
+An eid, or ebuild id, is an object that stores category, package, version and
+revision information.  eids can be valid or invalid.  If invalid, the eid will
+set an internal variable called "error" to a human-readable error message
+describing what is wrong with the eid.  Note that eids aren't tied to a
+particular ebuild file or package database entry; instead they're used by
+Portage to talk about particular category/package-version-revs in the abstract.
+Because all the information about a particular ebuild/db entry/.tbz2 package is
+stored in a single object, a lot of redundancy is eliminated.  Also, the eid
+methods make good use of caching in order to optimize performance for version
+comparisons, etc.
+
+Example use:
+
+>>> from portage_core import *
+>>> a=eid("sys-apps/foo-1.0")
+>>> a.valid
+1
+>>> a.version
+'1.0'
+>>> a.revision
+'0'
+>>> a.category
+'sys-apps'
+>>> b=eid("sys-apps/foo-1.1")
+>>> a>b
+0
+>>> a<b
+1
+>>> c=eid("sys-bad/packagename-1.0p3")
+>>> c.valid
+0
+>>> c.error
+'sys-bad/packagename-1.0p3: Invalid ending version part'
+
+(NOTE: the version string should be "1.0_p3", not "1.0p3".)
+
+Data Definitions:
+
+eid.repr: A human-readable represenation of the eid data, i.e. "sys-apps/foo-1.0-r1"
+eid.category: category, i.e. "sys-apps"
+eid.package: package, i.e. "foo"
+eid.version: version, i.e. "1.0"
+eid.revision: revision, i.e. "1"
+eid.valid: boolean specifying whether this is a valid eid, i.e. 1
+eid.error: a human-readable error message relating to a non-true eid.valid, i.e. "Invalid version part"
+eid.cmp: cached eid comparison data
+
+TEST ROUTINE: 
+
+for x in ["1.0_rc6","4.0_pre12", "4.0","9.12.13","0.9.10","1.0.9-r1","3.0","3.0_alpha1","3.0_beta","3.0_rc1","3.0_pre1","3.0_p3","3.0a"]:
+	a=eid("sys-apps/foo-"+x)
+	b=eid("sys-apps/foo-3.0")
+	a.debug()
+	if not a.valid:
+		print x,"(INVALID)"
+		continue
+	if a>b:
+		print x,">","3.0"
+	elif a<b:
+		print x,"<","3.0"
+	else:
+		print x,"=","3.0"
+"""
+
 class eid:
-	"An eid is an ebuild/package id, consisting of a category, package, version and revision"
+	"""An eid is an ebuild/package id, consisting of a category, package, version and revision.
+	If validate is set to 1 (the default), the init code will validate the input.  If set to zero,
+	the input is assumed correct, but an exception will be raised if it is not."""
+	
 	def __init__(self,mystring=None,validate=1):
 		"initialization; optional assignment; optional validation of input (otherwise assumed correct)"
 		
@@ -105,6 +173,7 @@ class eid:
 		self.repr=None
 	
 	def validateversion(self):	
+		"internal support routine that validates self.version"
 		myval=string.split(self.version,'.')
 		if len(myval)==0:
 			self.invalidate("Empty version string")
@@ -162,16 +231,17 @@ class eid:
 		return 0
 	
 	def debug(self):
+		"internal debug function"
 		print
 		print "DEBUG EID"
-		for x in ["error","category","package","version","revision","valid","repr"]:
+		for x in ["error","category","package","version","revision","valid","repr","cmp"]:
 			try:
 				exec("print x,self."+x)
 			except:
 				print x,"(undefined)"
 	
 	def __cmp__(self,other):
-		"comparison"
+		"comparison operator code"
 		if self.cmp==None:
 			self.cmp=self.gencmp()
 		if other.cmp==None:
@@ -237,16 +307,4 @@ class eid:
 				return 1
 		return 0
 
-for x in ["1.0_rc6","4.0_pre12", "4.0","9.12.13","0.9.10","1.0.9-r1","3.0","3.0_alpha1","3.0_beta","3.0_rc1","3.0_pre1","3.0_p3","3.0a"]:
-	a=eid("sys-apps/foo-"+x)
-	b=eid("sys-apps/foo-3.0")
-	a.debug()
-	if not a.valid:
-		print x,"(INVALID)"
-		continue
-	if a>b:
-		print x,">","3.0"
-	elif a<b:
-		print x,"<","3.0"
-	else:
-		print x,"=","3.0"
+