comments.

pisi/context.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# PISI configuration (static and dynamic)
+# Context module.
 
 from specfile import SpecFile
 from constants import const

pisi/fetcher.py

@@ -1,6 +1,9 @@
 # -*- coding: utf-8 -*-
-# download magic
-# maintainer: baris and meren
+
+# Yet another Pisi module for fetching files from various sources. Of
+# course, this is not limited to just fetching source files. We fetch
+# all kinds of things: source tarballs, index files, packages, and God
+# knows what.
 
 # python standard library modules
 import urlparse
@@ -15,10 +18,8 @@ class FetchError (Exception):
     pass
 
 class Fetcher:
-    """Yet another Pisi tool for fetching files from various sources..
-    Of course, this is not limited to just fetching source files.
-    We fetch all kinds of things: source tarballs, index files,
-    packages, and God knows what."""
+    """Fetcher can fetch a file from various sources using various
+    protocols."""
     def __init__(self, source):
         self.uri = source.archiveUri
         self.filedest = config.archives_dir()

pisi/files.py

@@ -1,11 +1,12 @@
- # class for files.xml
+# Files module provides access to files.xml. files.xml is genarated
+# during the build process of a package and used in installation.
 
 import xmlfile
 from xmlfile import XmlFile
 
 
 class FileInfo:
-    
+    """FileInfo holds the information for a File node/tag in files.xml"""
     def __init__(self, _path = "", _type = "", _size="", _hash = ""):
         self.path = _path
         self.type = _type

pisi/metadata.py

@@ -1,3 +1,7 @@
+# Metadata module provides access to metadata.xml. metadata.xml is
+# generated during the build process of a package and used in the
+# installation. Package repository also uses metadata.xml for building
+# a package index.
 
 from ui import ui
 
@@ -40,7 +44,7 @@ class PackageInfo(specfile.PackageInfo):
 
 class MetaData(XmlFile):
     """Package metadata. Metadata is composed of Specfile and various
-    other information."""
+    other information. A metadata has two parts, Source and Package."""
 
     def __init__(self):
         XmlFile.__init__(self,"PISI")

pisi/package.py

@@ -7,39 +7,41 @@ from constants import const
 from config import config
 
 class Package:
-    """Package: PISI package class"""
+    """PISI Package Class provides access to a pisi package (.pisi
+    file)."""
     def __init__(self, packagefn, mode='r'):
         self.impl = archive.ArchiveZip(packagefn, 'zip', mode)
         self.filename = packagefn
 
     def add_file(self, fn):
-        """add a file or directory to package"""
+        """Add a file or directory to package"""
         self.impl.add_file(fn)
 
     def close(self):
+        """Close the package archive"""
         self.impl.close()
 
     def extract(self, outdir):
-        """extract entire package contents to directory"""
+        """Extract entire package contents to directory"""
         extract_dir('', outdir)         # means package root
 
     def extract_files(self, paths, outdir):
-        """extract file with path to outdir"""
+        """Extract file with path to outdir"""
         self.impl.unpack_files(paths, outdir)
 
     def extract_dir(self, dir, outdir):
-        """extract directory recursively, this function
+        """Extract directory recursively, this function
         copies the directory archiveroot/dir to outdir"""
         self.impl.unpack_dir(path, outdir)
 
     def extract_dir_flat(self, dir, outdir):
-        """extract directory recursively, this function
+        """Extract directory recursively, this function
         unpacks the *contents* of directory archiveroot/dir inside outdir
         this is the function used by the installer"""
         self.impl.unpack_dir_flat(dir, outdir)
         
     def extract_PISI_files(self, outdir):
-        """extract PISI control files: metadata.xml, files.xml,
+        """Extract PISI control files: metadata.xml, files.xml,
         action scripts, etc."""
         self.extract_files([const.metadata_xml,
                             const.files_xml,'Config'], outdir)

pisi/specfile.py

@@ -1,10 +1,16 @@
 # -*- coding: utf-8 -*-
-# read/write PISI source package specification file
 
+# Specfile module is our handler for PSPEC files. PSPEC (PISI SPEC)
+# files are specification files for PISI source packages. This module
+# provides read and write access to PSPEC files.
+
+# standard python modules
 import xml.dom.minidom
+from os.path import basename
+
+# pisi modules
 from xmlext import *
 from xmlfile import XmlFile
-from os.path import basename
 from ui import ui
 
 class PackagerInfo:
@@ -74,7 +80,8 @@ class PathInfo:
         return node
 
 class SourceInfo:
-    "a structure to hold source information"
+    """A structure to hold source information. Source information is
+    located under <Source> tag in PSPEC file."""
     def __init__(self, node):
         self.name = getNodeText(node, "Name")
         self.homepage = getNodeText(node, "HomePage")
@@ -117,6 +124,9 @@ class SourceInfo:
         return node
 
 class PackageInfo:
+    """A structure to hold package information. Package information is
+    located under <Package> tag in PSPEC file. Opposite to Source each
+    PSPEC file can have more than one Package tag."""
     def __init__(self, node):
         self.name = getNodeText(node, "Name")
         self.summary = getNodeText(node, "Summary")

pisi/xmlfile.py

@@ -1,13 +1,16 @@
 # -*- coding: utf-8 -*-
-# some helper functions for using minidom
+
+# XmlFile is a halper module for accessing XML files using
+# xml.dom.minidom.
+#
+# XmlFile class that further abstracts a dom object using the
+# high-level dom functions provided in xml module (and sorely lacking
+# in xml.dom :( )
 
 import xml.dom.minidom as mdom
 
 from xmlext import *
 
-# xmlfile class that further abstracts a dom object
-# using the high-level dom functions provided in xml module
-# (and sorely lacking in xml.dom :( )
 
 class XmlFile(object):
     """A class for retrieving information from an XML file"""