add some inline documentation

explainshell/fixer.py

@@ -3,6 +3,10 @@
 from explainshell import util
 
 class basefixer(object):
+    '''The base fixer class which other fixers inherit from.
+
+    Subclasses override the base methods in order to fix manpage content during
+    different parts of the parsing/classifying/saving process.'''
     runbefore = []
     runlast = False
 
@@ -36,6 +40,7 @@ def pre_add_manpage(self):
 fixerspriority = {}
 
 class runner(object):
+    '''The runner coordinates the fixers.'''
     def __init__(self, mctx):
         self.mctx = mctx
         self.fixers = [f(mctx) for f in fixerscls]

explainshell/manager.py

@@ -102,12 +102,13 @@ def run(self):
                         assert len(mps) == 1
                         mp = mps[0]
                         if not self.overwrite or mp.updated:
-                            logger.info('manpage %r already in store, not overwriting it', m.name)
+                            logger.info('manpage %r already in the data store, not overwriting it', m.name)
                             exists.append(m)
                             continue
                 except errors.ProgramDoesNotExist:
                     pass
 
+                # the manpage is not in the data store; process and add it
                 ctx = self.ctx(m)
                 m = self.process(ctx)
                 if m:

explainshell/manpage.py

@@ -122,6 +122,7 @@ def _parsetext(lines):
         l = re.sub(_href, r'<a href="http://manpages.ubuntu.com/manpages/precise/en/man\2/\1.\2.html">', l)
         for lookfor, replacewith in _replacements:
             l = re.sub(lookfor, replacewith, l)
+        # confirm the line is valid utf8
         lreplaced = l.decode('utf8', 'ignore').encode('utf8')
         if lreplaced != l:
             logger.error('line %r contains invalid utf8', l)
@@ -176,6 +177,8 @@ def __init__(self, path):
         self._text = None
 
     def read(self):
+        '''Read the content from a local manpage file and store it in usable formats
+        on the class instance.'''
         cmd = [config.MAN2HTML, urllib.urlencode({'local' : os.path.abspath(self.path)})]
         logger.info('executing %r', ' '.join(cmd))
         self._text = subprocess.check_output(cmd, stderr=devnull, env=ENV)