From 5e232f1980c3e24bf80f624b97a13205086053e9 Mon Sep 17 00:00:00 2001
From: "Jauhien Piatlicki (jauhien)" <piatlicki@gmail.com>
Date: Fri, 20 Sep 2013 00:31:12 +0200
Subject: g_sorcery: comments in sources

---
 g_sorcery/backend.py       | 11 +++++++++++
 g_sorcery/fileutils.py     |  7 ++++++-
 g_sorcery/g_collections.py |  3 ++-
 g_sorcery/logger.py        | 24 ++++++++++++++++++++++++
 g_sorcery/package_db.py    | 13 ++++---------
 5 files changed, 47 insertions(+), 11 deletions(-)

diff --git a/g_sorcery/backend.py b/g_sorcery/backend.py
index 49b80fd..5b10574 100644
--- a/g_sorcery/backend.py
+++ b/g_sorcery/backend.py
@@ -588,6 +588,17 @@ class Backend(object):
         package_manager.install(args.pkgname, *args.pkgmanager_flags)
         
     def __call__(self, args, config, global_config):
+        """
+        Execute a command
+
+        Args:
+            args: Command line arguments.
+            config: Backend config.
+            global_config: g-sorcery config.
+
+        Returns:
+            Exit status.
+        """
         args = self.parser.parse_args(args)
         info_f = FileJSON(os.path.join(args.overlay, self.sorcery_dir),
                           "info.json", ["repositories"])
diff --git a/g_sorcery/fileutils.py b/g_sorcery/fileutils.py
index 24ad8e1..f444f4a 100644
--- a/g_sorcery/fileutils.py
+++ b/g_sorcery/fileutils.py
@@ -24,7 +24,8 @@ from .serialization import JSONSerializer, deserializeHook
 
 class FileJSON(object):
     """
-    Class for JSON files.
+    Class for JSON files. Supports custom JSON serialization
+    provided by g_sorcery.serialization.
     """
     def __init__(self, directory, name, mandatories=[]):
         """
@@ -110,6 +111,7 @@ def wget(uri, directory, output=""):
     Args:
         uri: URI.
         directory: Directory where file should be saved.
+        output: Name of output file.
 
     Returns:
         Nonzero in case of a failure.
@@ -125,6 +127,9 @@ def get_pkgpath(root = None):
     """
     Get package path.
 
+    Args:
+        root: module file path
+
     Returns:
         Package path.
     """
diff --git a/g_sorcery/g_collections.py b/g_sorcery/g_collections.py
index 104673d..b28db6a 100644
--- a/g_sorcery/g_collections.py
+++ b/g_sorcery/g_collections.py
@@ -7,7 +7,8 @@
     
     Customized classes of standard python data types
     for use withing g-sorcery for custom formatted string output
-    substitution in our ebuild templates.
+    substitution in our ebuild templates and classes for storing
+    information about packages and dependencies.
     
     :copyright: (c) 2013 by Brian Dolbec
     :copyright: (c) 2013 by Jauhien Piatlicki
diff --git a/g_sorcery/logger.py b/g_sorcery/logger.py
index 6617602..9fec3b6 100644
--- a/g_sorcery/logger.py
+++ b/g_sorcery/logger.py
@@ -41,16 +41,31 @@ class ProgressBar(object):
     __slots__ = ('length', 'total', 'processed', 'chars')
     
     def __init__(self, length, total, processed = 0):
+        """
+        Args:
+            length: Length of the progress bar.
+            total: The overall number of items to process.
+            processe: Number of processed items.
+        """
         self.length = length
         self.total = total
         self.chars = ['-', '\\', '|', '/']
         self.processed = processed
 
     def begin(self):
+        """
+        Start displaying the progress bar with 0% progress.
+        """
         self.processed = 0
         self.display()
 
     def display(self, processed = None):
+        """
+        Show the progress bar with current progress.
+
+        Args:
+            processed: Number of processed items.
+        """
         if processed:
             self.processed = processed
 
@@ -63,9 +78,18 @@ class ProgressBar(object):
         sys.stderr.flush()
 
     def increment(self, count = 1):
+        """
+        Increment number of processed items.
+
+        Args:
+            count: Step of incrementation.
+        """
         self.processed += count
         self.display()
 
     def end(self):
+        """
+        Show 100%.
+        """
         self.processed = self.total
         self.display()
diff --git a/g_sorcery/package_db.py b/g_sorcery/package_db.py
index 79b7ca1..13a6141 100644
--- a/g_sorcery/package_db.py
+++ b/g_sorcery/package_db.py
@@ -39,14 +39,7 @@ class PackageDB(object):
         manifest.json: database manifest
         categories.json: information about categories
         category1
-            packages.json: list of packages
-            package1
-                versions.json: list of versions
-                version1.json: description of a package
-                version2.json: description of a package
-                ...
-            package2
-            ...
+            packages.json: information about available packages
         category2
         ...
     
@@ -114,7 +107,6 @@ class PackageDB(object):
         self.logger = Logger()
         self.CATEGORIES_NAME = 'categories.json'
         self.PACKAGES_NAME = 'packages.json'
-        self.VERSIONS_NAME = 'versions.json'
         self.directory = os.path.abspath(directory)
         self.reset_db()
 
@@ -233,6 +225,9 @@ class PackageDB(object):
         self.write_and_manifest()
 
     def write_and_manifest(self):
+        """
+        Write and digest database.
+        """
         self.write()
         self.manifest()
 
-- 
cgit v1.2.3-65-gdbad