Add docstrings to most functions

3 files changed, 85 insertions, 6 deletions

diff --git a/src/matchbox/__init__.py b/src/matchbox/__init__.py
index 34c9daa..35eb1a2 100644
--- a/src/matchbox/__init__.py
+++ b/src/matchbox/__init__.py
@@ -17,6 +17,12 @@ import matchbox.db.main.models as dbm
 from matchbox.db import DjangoDB
 
 class MatchboxServer(object):
+    """
+    Class representing master Matchbox server deciding what needs to
+    be compiled. Tinderboxes connect to this server and ask for
+    packages to compile. When they return package contents (or errors)
+    Matchbox adds this information to database using DjangoDB backend.
+    """
 
     def __init__(self, host, port):
         self.host = host
@@ -26,6 +32,9 @@ class MatchboxServer(object):
         self.portsettings = portage.config(clone=portage.settings)
 
     def start_server(self):
+        """
+        Starts matchbox server waiting for Tinderbox connections
+        """
         try:
             self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
         except socket.error:
@@ -48,6 +57,15 @@ class MatchboxServer(object):
 
 
     def client_handler(self, client_socket, client_address):
+        """
+        Service for one Tinderbox connection accepting
+        commands/replies
+
+        @param client_socket: socket of client connection
+        @type client_socket: socket
+        @param client_address: (address,port) tuple of client
+        @type client_address: tuple
+        """
         while 1:
             buffer = client_socket.recv(4096)
             data = ""
@@ -89,6 +107,13 @@ class MatchboxServer(object):
         client_socket.close()
 
     def _get_next_package(self):
+        """
+        Returns category/package string of next pacakge to be compiled
+        by tinderbox(en)
+
+        @returns: category/package string
+        @rtype: string
+        """
         override  = self.__get_override_package()
         if override:
             return override
@@ -147,6 +172,11 @@ class MatchboxServer(object):
 
 
     def __get_override_package(self):
+        """
+        Function to simplify debugging. If file /tmp/matchbox_override
+        exists it reads first line and returns it. It's used to force
+        selection of certain package as next package for tinderbox to compile
+        """
         try:
             line = None
             fin = open("/tmp/matchbox_override","r")
diff --git a/src/protocol/__init__.py b/src/protocol/__init__.py
index b2ba89e..6841b88 100644
--- a/src/protocol/__init__.py
+++ b/src/protocol/__init__.py
@@ -1,6 +1,10 @@
 
 
-class MatchboxCommand(object): pass
+class MatchboxCommand(object):
+    """
+    Base class for Matchbox network commands
+    """
+    pass
 
 class GetNextPackage(MatchboxCommand):
     """
@@ -60,7 +64,11 @@ class AddPackageInfo(MatchboxCommand):
 
 
 
-class MatchboxReply(object): pass
+class MatchboxReply(object):
+    """
+    Base class for Matchbox network replies
+    """
+    pass
 
 class GetNextPackageReply(MatchboxReply):
     """
diff --git a/src/tinderbox/__init__.py b/src/tinderbox/__init__.py
index c90e0f7..641e12d 100644
--- a/src/tinderbox/__init__.py
+++ b/src/tinderbox/__init__.py
@@ -31,8 +31,14 @@ from logger import log, init_logging
 
 
 class Tinderbox(object):
+    """
+    Class for basic worker object called Tinderbox. Tinderbox connects to Matchbox
+    and asks for package(s) to compile. Tinderbox tries to compile given packages
+    and responds to Matchbox either with package contents or error messages
+    """
 
     NOMERGE_PKGS=['sys-apps/portage']
+    """These packages will never be (re)merged"""
 
     def __init__(self):
         self.hostname = config.MATCHBOX_HOST
@@ -48,12 +54,15 @@ class Tinderbox(object):
 
 
     def start_tinderbox(self):
+        """
+        This function starts tinderbox process (connects to Matchbox
+        server) and then starts compiling packages requested by
+        Matchbox.
+        """
         self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-        # TODO load settings for contacting matchbox 
         self.sock.connect((self.hostname,self.port))
 
         while 1:
-            # TODO error/exception checking
             msg = protocol.GetNextPackage()
             msg_pickled = pickle.dumps(msg)
             self.sock.sendall(msg_pickled)
@@ -77,6 +86,14 @@ class Tinderbox(object):
 
 
     def emerge_package(self, package):
+        """
+        Top level emerge function for compiling packages
+
+        @param package: package to be compiled, optionally with
+               version/useflag information
+        @type package: tinderbox Package
+        @return: None
+        """
         log.debug("emerge_package starting for %s" % package.name)
         settings = self.settings
 
@@ -167,10 +184,24 @@ class Tinderbox(object):
 
             msg = protocol.AddPackageInfo(package_infos)
             self.sock.sendall(pickle.dumps(msg))
-        #TODO make binpkg
 
 
     def _emerge_package_subprocess(self, pkg, dep_groups, package):
+        """
+        This functions is running inside chrooted environment. It's
+        purpose is to try and emerge packages group-by-group and then
+        package specified. All information is stored inside
+        package_infos to be retrieved later by calling function
+
+        @param pkg: cpv string (category/package-version)
+        @type pkg: string
+        @param dep_groups: dependency groups as returned by create_dep_groups function
+        @type dep_groups: list of lists of dependency cpvs
+        @param package: package class for filling out information
+        @type package: tinderbox.Package
+
+        @return None
+        """
         # We are chrooted inside WORK_CHROOT remember!
         porttree = self.trees[portage.root]['porttree']
         portdb = porttree.dbapi
@@ -283,6 +314,16 @@ class Tinderbox(object):
         self._save_info('package_infos', package_infos)
 
     def _add_attachment(self, pkg, path):
+        """
+        Adds file content with given path to package pkg as attachment
+
+        @param pkg: Package that will get embedded data
+        @type pkg: tinderbox.Package
+        @param path: Path to attachment file
+        @type path: string
+
+        @return None
+        """
         try:
             attfile = open(path,"r")
         except IOError, (errno, strerror):
@@ -504,5 +545,5 @@ class Package(object):
         cat, pkg = portage.catsplit(cpv)
         dblink = portage.dblink(cat, pkg, portage.root, vartree.settings, 
                     treetype="vartree", vartree=vartree)
-
+        
         return dblink.getcontents()