Add some more comment to the code

6 files changed, 28 insertions, 10 deletions

diff --git a/g_cran/cran_read.py b/g_cran/cran_read.py
index 5be0e0b..2da4420 100644
--- a/g_cran/cran_read.py
+++ b/g_cran/cran_read.py
@@ -16,7 +16,7 @@ def portage_dir():
                 portage_location=re.sub('\$\{.+?\}','',line[line.find('=')+1:]).strip() #remove ${ROOT} and other variables (lucky guess, lol)
     elif os.path.exists('/etc/make.conf'): #portage stores portage location here
         conffile=open('/etc/make.conf')
-        for line in conffile:
+        for line in conffile: #find PORTDIR="blabla" line
             find_portdir=re.match('\s*PORTDIR\s*=\s*"?(.*)"?\s*',line)
             if find_portdir:
                 portage_location=find_portdir.group(1).strip()
@@ -65,7 +65,7 @@ def pmsify_license_field(license_list):
             try_license=license_part+'-1'
         for license in available_licenses:
             if license==license_part or try_license==license:
-                licenses.append(license)
+                licenses.append(license) #match, append
                 break
         else:
             licenses.append('as-is') #unknown
@@ -94,12 +94,14 @@ def listify_package_list(package_list):
             packages.append(package_part[0])
     return packages
 
+#what core packages are installed by the R package in portage?
 R_core_packages=['base','datasets','grDevices','graphics','grid','methods','splines',
     'stats','stats4','tcltk','tools','utils',]
 R_recommended_packages=['KernSmooth','MASS','Matrix','base','boot','class','cluster',
     'codetools','datasets','foreign','grDevices','graphics','grid','lattice','methods',
     'mgcv','nlme','nnet','rpart','spatial','splines','stats','stats4','survival','tcltk',
     'tools','utils',]
+#parse dependency list
 def pmsify_package_list(package_list, cran_packages):
     #note: the following returns a list of tuples
     pms_packages=[]
@@ -119,7 +121,8 @@ def pmsify_package_list(package_list, cran_packages):
             pms_packages.append('dev-R/'+pmsify_package_name(package))
     return pms_packages
 
-#Parse package options into values we can work with in accordance with PMS
+#Parse package data loaded from the PACKAGES file
+#into values we can work with in accordance with PMS
 def pmsify_package_data(data,remote_repository):
     pms_pkg=Ebuild()
     pms_pkg.cran_data=data
@@ -176,6 +179,8 @@ def read_packages(package_filename,local_repository):
         package.ebuild_vars['pdepend']=deps
     return packages.values()
 
+#find a package in this repository... we really should cache this
+#into some sqlite database once
 def find_package(repo_location,package_name):
     packages=read_packages(os.path.join(repo_location,REPO_MYDIR,'PACKAGES'),repo_location)
     for package in packages:
diff --git a/g_cran/ebuild.py b/g_cran/ebuild.py
index 14d6af8..1beb55c 100644
--- a/g_cran/ebuild.py
+++ b/g_cran/ebuild.py
@@ -1,4 +1,3 @@
-#!/usr/bin/python
 #Class for PMS-style packages
 class Ebuild():
     def __init__(self):
diff --git a/g_cran/filetricks.py b/g_cran/filetricks.py
index e42e059..de99f3b 100644
--- a/g_cran/filetricks.py
+++ b/g_cran/filetricks.py
@@ -1,4 +1,6 @@
-#!/usr/bin/python
+#we use this class to easily read the PACKAGES file
+#an empty line denotes a new package, but readline() usually
+#doesn't return empty lines
 class EmptyLinesFile:
     def __init__(self,myfile):
         self.file=myfile
diff --git a/g_cran/g_cran.py b/g_cran/g_cran.py
index 69dddee..ce38de4 100644
--- a/g_cran/g_cran.py
+++ b/g_cran/g_cran.py
@@ -7,6 +7,7 @@ from settings import *
 
 __doc__="Usage: "+sys.argv[0]+" <local repository directory> <action> [<action arguments>...]"
 
+#sync a local repository's PACKAGES file
 def action_sync(repo_location,remote_uri):
     if not os.path.isdir(os.path.join(repo_location, REPO_MYDIR)):
         os.mkdir(os.path.join(repo_location,REPO_MYDIR))
@@ -15,14 +16,18 @@ def action_sync(repo_location,remote_uri):
     repo_file=open(os.path.join(repo_location,REPO_MYDIR,'remote_uri'),'w')
     repo_file.write(remote_uri)
 
+#list categories in this repositorie
 def list_categories(repo_location):
     print "dev-R"
 
+#idem ditto
 def list_packages(repo_location):
     packages=read_packages(os.path.join(repo_location,REPO_MYDIR,'PACKAGES'),repo_location)
     for package in packages:
         print 'dev-R/'+package.ebuild_vars['pn'],package.ebuild_vars['pv']
 
+#generate a tree of ebuilds... note that we only link ebuild files
+#metadata.xml and Manifest and whatnot is not generated
 def generate_tree(repo_location):
     packages=read_packages(os.path.join(repo_location,REPO_MYDIR,'PACKAGES'),repo_location)
     ebuild_file=os.path.join(os.path.dirname(__file__),'cran.ebuild')
@@ -32,6 +37,7 @@ def generate_tree(repo_location):
             os.makedirs(ebuild_dir)
         os.symlink(ebuild_file,os.path.join(ebuild_dir,package.ebuild_vars['pn']+'-'+package.ebuild_vars['pv']+'.ebuild'))
 
+#list package details, in PMS's format
 def action_package(repo_location,package_name):
     defined_phases=[]
     package=find_package(repo_location,package_name[package_name.find('/')+1:])
diff --git a/g_cran/phases.py b/g_cran/phases.py
index c5265c7..59dd683 100644
--- a/g_cran/phases.py
+++ b/g_cran/phases.py
@@ -17,6 +17,8 @@ def src_compile(env,local_repository):
     os.putenv('R_PLATFORM',R_PLATFORM) #force predictable package name
     os.chdir(env['WORKDIR'])
     tarball=os.path.join(env['DISTDIR'],env['A'])
+
+    #tmp_target is a dummy directory to make R CMD INSTALL function nicely
     tmp_target=os.path.join(env['WORKDIR'],'tmp_install')
     os.makedirs(tmp_target)
     returnval=verbose_system("R CMD INSTALL --build "+tarball+" -l "+tmp_target)
@@ -26,7 +28,11 @@ def src_compile(env,local_repository):
 def src_install(env,local_repository):
     package=cran_read.find_package(local_repository,env['PN'])
     os.putenv('R_PLATFORM',R_PLATFORM)
+
+    #figure out the name of the tarball we generated in src_compile
     tarname=env['WORKDIR']+'/'+package.cran_data['package']+'_'+package.cran_data['version']+'_R_'+R_PLATFORM+'.tar.gz' #assume always gzip
+
+    #figure out target install dir
     r_home=os.getenv('R_HOME')
     if len(r_home)==0: #R home isn't set, try to read /etc/env.d/99R
         envfile=open('/etc/env.d/99R','r')
@@ -38,8 +44,8 @@ def src_install(env,local_repository):
             raise RuntimeError("Could not deduce R_HOME")
     r_library=env['D']+r_home+"/library"
     if not os.path.exists(r_library):
-        os.makedirs(r_library)
-    #install the binary package without documentation (excluding documentation doesn't seem to work)
+        os.makedirs(r_library) #note this is all just in env['D']
+    #install the binary package
     returnval=verbose_system("R CMD INSTALL --debug "+tarname+" -l "+r_library)
     if returnval:
         raise RuntimeError("R install failed")
@@ -49,7 +55,7 @@ def src_install(env,local_repository):
     except:
         pass
     
-    #todo install HTML help
+    #todo install non-HTML help
     doc_dir=env['D']+'/usr/share/doc/'+env['PF']
     if 'doc' in package.ebuild_vars['iuse'] and 'doc' in env['USE']:
         os.makedirs(doc_dir)
diff --git a/g_cran/settings.py b/g_cran/settings.py
index 1da3a16..baff761 100644
--- a/g_cran/settings.py
+++ b/g_cran/settings.py
@@ -1,5 +1,5 @@
-
+#what phases can we have in our ebuild?
 pms_phases=['pkg_pretend','pkg_setup','src_unpack','src_prepare','src_configure','src_compile',
     'src_test','src_install','pkg_preinst','pkg_postinst','pkg_prerm','pkg_postrm','pkg_config','pkg_info','pkg_nofetch']
 actions_wanted=['usage','sync','list-categories','list-packages','package']+pms_phases
-REPO_MYDIR=".g-cran"
+REPO_MYDIR=".g-cran" #hidden directory to save our data in a local repo