adds 135 kilocraps of documentation

135 kilocraps = 1 metric craptonne

1 files changed, 58 insertions, 9 deletions

diff --git a/modules/darcs.py b/modules/darcs.py
index dddaee2..8bee4a4 100644
--- a/modules/darcs.py
+++ b/modules/darcs.py
@@ -32,29 +32,47 @@ hash_re = re.compile(r'hash=\'(\w|-|.*?)\'', re.MULTILINE)
 date_re = re.compile(r'date=\'(\d*?)\'', re.MULTILINE)
 
 class Darcs(RevisionControl):
+    '''manages single source packages where the primary source is darcs
+    '''
     _type = 'darcs'
-    def load_dir(self, dir):
-        super(RevisionControl, self).load_dir(dir)
-
     @property
     def vc_url(self):
+        '''the url where the source was fetched from originally
+
+        this may be moved to revision control in the future
+        '''
         return self.cfg['vc_url']
 
     @property
     def hackage_name(self):
+        '''assuming this package is a haskell package, what is the canonical name
+        
+        this name may be changed in the future
+        '''
         return self.cfg['hackage_name']
 
     def source(self, *args):
+        '''the name of the directory where the source is being kept currently
+
+        hackage_name is the canonical name of the package, this is 
+        just for handling branching and other nasty devilish tricks
+        '''
         return self.cfg['source']
 
     @contextmanager
     def src_dir(self, *args):
+        '''executes a code block inside a specific branch and or checkout
+        '''
         with src(*args):
             with pwd(self.cfg['source']):
                 yield
 
     @contextmanager
     def src(self, *args):
+        '''executes a code block with a particular branch or checkout
+
+        if there are no args, this block is executed in the raw
+        '''
         if args:
             old_src = self.cfg['source']
             self.set_cur_to(*args)
@@ -66,6 +84,14 @@ class Darcs(RevisionControl):
 
 
     def get(self, src, tgt, *args):
+        '''sets up a branch given arguments, taken from a source with a target
+        
+        the idioms of branching in different VCSes vary, and a common 
+        api for this in devshell has not yet been realized
+
+        currently, this creates a new temporary local branch in darcs 
+        and sets the source to it
+        '''
         with pwd(self.dir):
             self.cfg['source'] = tgt
             with log_file('darcs.log') as darcs_out:
@@ -76,11 +102,25 @@ class Darcs(RevisionControl):
             self.set_current_head()
 
     def checkout(self, tgt, url, *args):
+        '''checks out source from an upstream url
+
+        the difference between this and get is that it reflects an initial pull
+        idiom found in other VCSes. It also handles setting vc_url and the 
+        canonical name, based on tgt
+        '''
         self.cfg['vc_url'] = url
         self.cfg['hackage_name'] = split(tgt)[1]
         self.get(url, tgt, *args)
 
     def set_current_head(self):
+        '''sets the current internal state to reflect the current head
+
+        chances are, the user should rarely mess with this.
+
+        this may change, because rather than using .patch files for rpm 
+        handling, we may ask the user to commit all the changes to darcs, 
+        and then have devshell generate .patch files automatically instead
+        '''
         log.debug(getcwd())
         with pwd(self.cfg['source']):
             p = Popen(['darcs', 'changes', '--xml-output', '--last=1'],
@@ -91,48 +131,57 @@ class Darcs(RevisionControl):
             self.cfg['head'] = (hash, date)
 
     def set_cur_to(self, *args):
+        '''passes arbitrary args to darcs get and makes a branch out of it
+        
+        this is not really optimal, because it only does things temporary,
+        we need to look at as systematic way to handle branching. 
+        looking at a potential git and a potential cvs module may help
+        '''
         cur_src_dir = self.cfg['source']
         new_src_dir = cur_src_dir + '_tmp'
         self.get(cur_src_dir, new_src_dir, *args)
 
     def set_cur_to_patch(self, hash):
+        '''sets the current branch to fork off a particular hash'''
         self.set_cur_to('--to-match', 'hash ' + hash)
 
     def set_cur_to_tag(self, tag):
+        '''sets the current branch to fork off a particular tag'''
         self.set_cur_to('--tag', tag)
 
     @property
     def date(self):
+        '''get's the timestamp of the latest patch on HEAD of the current branch'''
         return self.cfg['head'][1]
 
     @property
     def hash(self):
+        '''gets the hash of the latest patch on HEAD of the current branch'''
         return self.cfg['head'][0]
 
     def print_date(self):
+        '''prints the timestamp of the latest patch on HEAD of the current branch'''
         log.info('The timestamp is ' + self.date)
 
     def print_hash(self):
+        '''prints the hash of the latest patch on HEAD of the current branch'''
         log.info('The hash is ' + self.hash)
 
-    def set_cur_to_patch(self, hash):
-        self.set_cur_to('--to-match', 'hash ' + hash)
-
-    def set_cur_to_tag(self, tag):
-        self.set_cur_to('--tag', tag)
-
     @contextmanager
     def patch(self, hash):
+        '''executes a block of code on top a particular patch'''
         with self.src('--to-match', 'hash ' + hash):
             yield
 
     @contextmanager
     def tag(self, tag):
+        '''executes a particular block of code on top of a particular tag'''
         with self.src('--tag', tag):
             yield
 
 
     def setup_sourceball(self):
+        '''gets darcs to spit out a sourceball to be used in rpm making by other modules'''
         log.debug('someone set us up the bomb')
         with pwd(self.dir):
             with pwd(self.source_dir()):