Updating Docs

core/create.py

@@ -15,10 +15,10 @@
 
 def main(config, info):
     '''
-    This is pacbacks main method for orchestrating the creating of a
+    This is pacbacks main method for orchestrating the creation of a
     fallback point. It shouldn't be called directly with create.main()
-    but with a 'higher' level call the builds the info and stages the
-    system for the actual creation process.
+    but rather by a 'higher' level call that stages system for the
+    actual creation process.
     '''
     fname = 'create.main(' + info['type'] + info['id'] + ')'
     paf.write_to_log(fname, 'Building ID:' + info['id'] + ' As ' + info['STYPE'] + ' ' + info['TYPE'], config['log'])
@@ -113,8 +113,8 @@ def main(config, info):
 
 def snapshot(config, label):
     '''
-    Assembles all the info and stages the file system needed for the creation
-    of a new snapshot with id:00. This is only called by `pacback --hook`.
+    Assembles all the info for main() and stages the file system for the creation
+    of a new snapshot with id='00'. This is only called by `--hook`.
     '''
     num = '00'
     fname = 'create.snapshot(' + num + ')'
@@ -193,8 +193,9 @@ def snapshot(config, label):
 
 def restore_point(config, num, full_rp, dir_list, no_confirm, label):
     '''
-    Assembles all the info and stages the file system needed for the creation
-    of a restore point. It is assumed that user info is cleansed.
+    Assembles all the info for main() and stages the file system
+    for the creation of a restore point. It is assumed that user input
+    has been cleansed by this point.
     '''
     num = str(num).zfill(2)
     fname = 'create.restore_point(' + num + ')'

core/meta.py

@@ -58,7 +58,7 @@ def read(config, meta_path):
 
 def compare(config, old_pkgs, new_pkgs):
     '''
-    Compares two list of packages and returns a dictionary containing
+    Compares two lists of packages and returns a dictionary containing
     changed, added, and removed packages. Also returns a formated list
     for searching with utils.search_cache().
     '''

core/restore.py

@@ -17,7 +17,8 @@
 
 def main(config, parms, pkg_results):
     '''
-    This is the main restore logic for pacback. It should NOT be called directly as restore.main().
+    This is the main restore logic for pacback. It should NOT be called directly but
+    instead called through a higher level 'API' like call.
     This logic does the actual work of downgrading, removing, and installing packages.
     '''
     fname = 'restore.main(' + parms['type'] + parms['id'] + ')'
@@ -190,8 +191,8 @@ def restore_point(config, id_num):
 def packages(config, pkgs):
     '''
     Allows the user to rollback packages by name.
-    Packages are not sent to pacman until the user has select all
-    the packages they want to restore/change.
+    Packages are not sent to pacman until the user has 
+    selected all the packages they want to restore/change.
     '''
     # Startup
     fname = 'restore.packages(' + str(len(pkgs)) + ')'

core/session.py

@@ -14,8 +14,8 @@
 
 def lock(config):
     '''
-    This checks if pacback is being run by root or sudo.
-    Then checks if an active session is already in progress.
+    This checks if pacback is being run by root or sudo,
+    then checks if an active session is already in progress.
     '''
     fname = 'session.lock()'
     if paf.am_i_root() is False:
@@ -36,8 +36,8 @@ def lock(config):
 
 def unlock(config):
     '''
-    Removes the session lock defined by config['slock'].
-    This releases the lock that was created by session.lock()
+    Removes the session lock file defined by config['slock'].
+    This will release the lock that was created calling session.lock()
     '''
     fname = 'session.unlock()'
     paf.write_to_log(fname, 'Ended Active Session', config['log'])
@@ -47,7 +47,7 @@ def unlock(config):
 def abort_fail(func, output, message, config):
     '''
     This is a surrogate function for other functions to safely abort runtime during a failure.
-    It reports the func sending the kill signal as the origin, rather than session.abort().
+    It reports the func sending the kill request as the origin, rather than session.abort().
     '''
     paf.write_to_log(func, 'FAILURE: ' + output, config['log'])
     unlock(config)
@@ -57,18 +57,19 @@ def abort_fail(func, output, message, config):
 
 def abort(func, output, message, config):
     '''
-    This is a surrogate function for other functions to safely abort runtime.
+    This is a surrogate function for other functions to safely abort runtime WITHOUT reporting
+    as an internal error. This is useful for non-critical issues that still require a runtime exit.
     It reports the func sending the kill signal as the origin, rather than session.abort().
     '''
     paf.write_to_log(func, 'ABORT: ' + output, config['log'])
     unlock(config)
     paf.prBold(message)
-    sys.exit()
+    sys.exit(0)
 
 
 def sig_catcher(log, signum, frame):
     '''
-    This is called whenever a exit signal is received.
+    This is called whenever a exit signal is received(AKA: KeyboardInterupt).
     It lets pacback exit somewhat safely during the event of a kill.
     '''
     abort_fail('SIGINT', 'Caught SIGINT ' + str(signum), '\nAttempting Clean Exit', log)
@@ -81,7 +82,7 @@ def sig_catcher(log, signum, frame):
 def hlock_start(config):
     '''
     This starts a hook lock overwriting the previous lock.
-    This should be triggered at the end of a successful --hook run.
+    This should be triggered at the end of a successful `--hook` run.
     '''
     fname = 'session.hlock_start(' + str(config['hook_cooldown']) + ')'
     stime = 'Created: ' + dt.datetime.now().strftime("%Y:%m:%d:%H:%M:%S"),

core/user.py

@@ -95,10 +95,10 @@ def list_all(config):
 
 def print_info(config, selction):
     '''
-    This function processes a meta data file without validating it.
-    It will compare the file to now and present the results in a table.
+    This function processes a meta data file without validating it,
+    then compares the file to now and presents the results in a table.
     This acts as a 'dry run' of sorts not only showing info in the meta data
-    file but also showing what would be changed.
+    file but also showing what would be changed if actually restored.
     The code is kind of gross but I'm not inclined to fix it.
     '''
     # Build Base Vars

core/utils.py

@@ -139,7 +139,7 @@ def find_cache_paths(config):
 
 def pacman_Q():
     '''
-    Captures the output of `pacman -Q`
+    Captures the output of `pacman -Q` from stdout
     '''
     raw = subprocess.Popen('/usr/bin/pacman -Q', stdout=subprocess.PIPE, shell=True)
     out = str(raw.communicate())[3:]
@@ -204,9 +204,9 @@ def scan_caches(config):
 
 def search_cache(pkg_list, fs_list, config):
     '''
-    Searches the cache for matching pkg versions and returns results.
-    Because of the way files are named, and the output given by pacman -Q
-    regex is needed to find the version reported to the package path.
+    Searches the cache for matching pkg versions and returns the results.
+    Because of the way files are named and the output given by pacman -Q,
+    regex is needed to find the version in the cached package path.
     No performance is gained with more than 4 threads on this function.
     '''
     fname = 'utils.search_cache(' + str(len(pkg_list)) + ')'
@@ -236,8 +236,8 @@ def search_cache(pkg_list, fs_list, config):
 
 def pacman_hook(install, config):
     '''
-    Installs or removes a standard alpm hook in /etc/pacman.d/hooks
-    This runs as a PreTransaction hook during every transaction.
+    Installs or removes a standard alpm hook in /usr/share/libalpm/hooks/
+    which runs as a PreTransaction hook during every pacman transaction.
     `install = True` Installs Pacman Hook
     `install = False` Removes Pacman Hook
     '''
@@ -280,8 +280,8 @@ def pacman_hook(install, config):
 
 def reboot_check(config):
     '''
-    Checks running and installed kernel versions to determine if
-    a reboot is needed.
+    Checks the running and installed kernel versions 
+    to determine if a reboot is needed.
     '''
     fname = 'utils.reboot_check()'