Correct and clarify docs and comments.

docs/reference/pip_install.rst

@@ -475,8 +475,8 @@ against any requirement not only checks that hash but also activates
   actor could slip bad code into the installation via one of the unhashed
   requirements. Note that hashes embedded in URL-style requirements via the
   ``#md5=...`` syntax suffice to satisfy this rule (regardless of hash
-  strength, for legacy reasons), though you use a stronger hash like sha256
+  strength, for legacy reasons), though you should use a stronger
-  whenever possible.
+  hash like sha256 whenever possible.
 * Hashes are required for all dependencies. An error is raised if there is a
   dependency that is not spelled out and hashed in the requirements file.
 * Requirements that take the form of project names (rather than URLs or local

pip/download.py

@@ -674,10 +674,11 @@ def unpack_file_url(link, location, download_dir=None, hashes=None):
             logger.info('Link is a directory, ignoring download_dir')
         return
 
-    # If --require-hashes is off, `hashes` is either empty, the link hash, or
+    # If --require-hashes is off, `hashes` is either empty, the
-    # MissingHashes, and it's required to match. If --require-hashes is on, we
+    # link's embeddded hash, or MissingHashes; it is required to
-    # are satisfied by any hash in `hashes` matching: a URL-based or an
+    # match. If --require-hashes is on, we are satisfied by any
-    # option-based one; no internet-sourced hash will be in `hashes`.
+    # hash in `hashes` matching: a URL-based or an option-based
+    # one; no internet-sourced hash will be in `hashes`.
     if hashes:
         hashes.check_against_path(link_path)
 
@@ -744,7 +745,7 @@ def unpack_url(link, location, download_dir=None,
          - if only_download, mark location for deletion
 
     :param hashes: A Hashes object, one of whose embedded hashes must match,
-        or I'll raise HashMismatch. If the Hashes is empty, no matches are
+        or HashMismatch will be raised. If the Hashes is empty, no matches are
         required, and unhashable types of requirements (like VCS ones, which
         would ordinarily raise HashUnsupported) are allowed.
     """

pip/req/req_install.py

@@ -1038,11 +1038,12 @@ exec(compile(
         """Return a hash-comparer that considers my option- and URL-based
         hashes to be known-good.
 
-        Hashes in URLs are almost peers with ones from flags. They satisfy
+        Hashes in URLs--ones embedded in the requirements file, not ones
-        --require-hashes (whether it was implicitly or explicitly activated)
+        downloaded from an index server--are almost peers with ones from
-        but do not activate it. md5 and sha224 are not allowed in flags, which
+        flags. They satisfy --require-hashes (whether it was implicitly or
-        should nudge people toward good algos. We always OR all hashes
+        explicitly activated) but do not activate it. md5 and sha224 are not
-        together, even ones from URLs.
+        allowed in flags, which should nudge people toward good algos. We
+        always OR all hashes together, even ones from URLs.
 
         :param trust_internet: Whether to trust URL-based (#md5=...) hashes
             downloaded from the internet, as by populate_link()