Improve docstrings and comments

pip/basecommand.py

@@ -191,8 +191,8 @@ def main(self, args):
                 deprecation.RemovedInPip11Warning,
             )
 
-        # TODO: try to get these passing down from the command?
-        #      without resorting to os.environ to hold these.
+        # TODO: Try to get these passing down from the command without
+        #       resorting to os.environ to hold these?
 
         if options.no_input:
             os.environ['PIP_NO_INPUT'] = '1'
@@ -212,8 +212,8 @@ def main(self, args):
 
         try:
             status = self.run(options, args)
-            # FIXME: all commands should return an exit status
-            # and when it is done, isinstance is not needed anymore
+            # FIXME: All commands should return an exit status
+            #        and when it is done, isinstance is not needed anymore
             if isinstance(status, int):
                 return status
         except PreviousBuildDirError as exc:

pip/cache.py

@@ -19,12 +19,11 @@
 class Cache(object):
     """An abstract class - provides cache directories for data from links
 
-
-        :param cache_dir: The root of the cache.
-        :param format_control: A pip.index.FormatControl object to limit
-            binaries being read from the cache.
-        :param allowed_formats: which formats of files the cache should store.
-            ('binary' and 'source' are the only allowed values)
+    :param cache_dir: The root of the cache.
+    :param format_control: A pip.index.FormatControl object to limit
+                           binaries being read from the cache.
+    :param allowed_formats: Which formats of files the cache should store.
+                            ('binary' and 'source' are the only allowed values)
     """
 
     def __init__(self, cache_dir, format_control, allowed_formats):
@@ -70,6 +69,7 @@ def _get_candidates(self, link, package_name):
         if can_not_cache:
             return []
 
+        # Check if the format of this cache is allowed to be used
         canonical_name = canonicalize_name(package_name)
         formats = pip.index.fmt_ctl_formats(
             self.format_control, canonical_name

pip/commands/uninstall.py

@@ -46,6 +46,8 @@ def __init__(self, *args, **kw):
     def run(self, options, args):
         with self._build_session(options) as session:
             reqs_to_uninstall = {}
+
+            # Determine which requirements have been given
             for name in args:
                 req = InstallRequirement.from_line(
                     name, isolated=options.isolated_mode,

pip/operations/prepare.py

@@ -210,9 +210,8 @@ def _prepare_linked_requirement(self, req, resolver):
                 resolver.require_hashes
             )
             # We can't hit this spot and have populate_link return None.
-            # req.satisfied_by is None here (because we're
-            # guarded) and upgrade has no impact except when satisfied_by
-            # is not None.
+            # req.satisfied_by is None here (because we're guarded) and upgrade
+            # has no impact except when satisfied_by is not None.
             # Then inside find_requirement existing_applicable -> False
             # If no new versions are found, DistributionNotFound is raised,
             # otherwise a result is guaranteed.
@@ -224,11 +223,10 @@ def _prepare_linked_requirement(self, req, resolver):
             # than otherwise. (For example, we can raise VcsHashUnsupported
             # for a VCS URL rather than HashMissing.)
             if resolver.require_hashes:
-                # We could check these first 2 conditions inside
-                # unpack_url and save repetition of conditions, but then
-                # we would report less-useful error messages for
-                # unhashable requirements, complaining that there's no
-                # hash provided.
+                # We could check these first 2 conditions inside unpack_url
+                # and save repetition of conditions, but then we would report
+                # less-useful error messages for unhashable requirements,
+                # complaining that there's no hash provided.
                 if is_vcs_url(link):
                     raise VcsHashUnsupported()
                 elif is_file_url(link) and is_dir_url(link):

pip/utils/temp_dir.py

@@ -30,7 +30,7 @@ class TempDirectory(object):
             Deletes the temporary directory and sets path attribute to None
 
     When used as a context manager, a temporary directory is created on
-    entering the context and, if the delete attribute is True, on exiting the
+    entering the context and if the delete attribute is True, on exiting the
     context the created directory is deleted.
     """
 

pip/wheel.py

@@ -806,7 +806,7 @@ def build(self, session, autobuilding=False):
                 if wheel_file:
                     build_success.append(req)
                     if autobuilding:
-                        # XXX: This is mildly duplicative with prepare_files,
+                        # XXX: This is mildly duplicative with Resolver,
                         # but not close enough to pull out to a single common
                         # method.
                         # The code below assumes temporary source dirs -
@@ -824,7 +824,7 @@ def build(self, session, autobuilding=False):
                         # Delete the source we built the wheel from
                         req.remove_temporary_source()
                         # set the build directory again - name is known from
-                        # the work prepare_files did.
+                        # the work Resolver did.
                         req.source_dir = req.build_location(
                             self.preparer.build_dir
                         )