From af6b5d4b24284e6b54e4e6b39dacd2020bc8b528 Mon Sep 17 00:00:00 2001
From: Brian Harring <ferringb@gentoo.org>
Date: Tue, 9 Aug 2005 07:55:06 +0000
Subject: doc updates

---
 portage/ebuild/eclass_cache.py | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/portage/ebuild/eclass_cache.py b/portage/ebuild/eclass_cache.py
index 28a1cc1..1924ca5 100644
--- a/portage/ebuild/eclass_cache.py
+++ b/portage/ebuild/eclass_cache.py
@@ -1,20 +1,21 @@
 # Copyright: 2005 Gentoo Foundation
 # Author(s): Brian Harring (ferringb@gentoo.org)
 # License: GPL2
-# $Header: /local/data/ulm/cvs/history/var/cvsroot/gentoo-src/portage/portage/ebuild/eclass_cache.py,v 1.3 2005/07/20 14:33:12 ferringb Exp $
+# $Header: /local/data/ulm/cvs/history/var/cvsroot/gentoo-src/portage/portage/ebuild/eclass_cache.py,v 1.4 2005/08/09 07:55:06 ferringb Exp $
 
 from portage.util.fs import normpath
 import os, sys
 
 class cache:
 	"""
-	Maintains the cache information about eclasses used in ebuild.
+	Maintains the cache information about eclasses available to an ebuild.
 	get_eclass_path and get_eclass_data are special- one (and only one) can be set to None.
 	Any code trying to get eclass data/path will choose which method it prefers, falling back to what's available if only one option
 	exists.
 
-	get_eclass_path should be defined when local path is possible/preferable.
-	get_eclass_data should be defined when dumping the eclass down the pipe is preferable/required (think remote tree)
+	get_eclass_path should be defined when it's possible to state the actual on disk location 
+	get_eclass_data should be defined when it's not possible (or not preferable), as such 
+	dumping the eclass down the pipe is required (think remote tree)
 
 	Base defaults to having both set.  Override as needed.
 	Set to None if that method isn't possible.
@@ -28,6 +29,7 @@ class cache:
 
 
 	def update_eclasses(self):
+		"""force instance to update it's internal view of on disk/remote eclasses"""
 		self.eclasses = {}
 		eclass_len = len(".eclass")
 		for x in [normpath(os.path.join(y,"eclass")) for y in self.porttrees]:
@@ -43,6 +45,9 @@ class cache:
 	
 
 	def is_eclass_data_valid(self, ec_dict):
+		"""given a dict as returned by get_eclass_data, walk it comparing it to internal eclass view
+		returns a boolean representing whether that eclass data is still up to date, or not
+		"""
 		if not isinstance(ec_dict, dict):
 			return False
 		for eclass, tup in ec_dict.iteritems():
@@ -53,6 +58,11 @@ class cache:
 
 
 	def get_eclass_data(self, inherits, from_master_only=False):
+		"""given a list of inherited eclasses, return the cachable eclass entries
+		only make get_eclass_data calls for data you know came from this eclass_cache, otherwise be ready to cache a KeyError 
+		exception for any eclass that was requested, but not known to this cache
+		"""
+
 		ec_dict = {}
 		for x in inherits:
 			try:
@@ -67,7 +77,7 @@ class cache:
 		return ec_dict
 
 	def get_eclass_path(self, eclass):
-		"""get on disk eclass path.  remote implementations need a way to say 'piss off tool' if this is called..."""
+		"""get local file path to an eclass.  remote implementations should set this to None, since the file isn't locally available"""
 		return os.path.join(self.eclasses[eclass][0],eclass+".eclass")
 
 	def get_eclass_contents(self, eclass):
-- 
cgit v1.2.3-65-gdbad