Add comments explaining InstallationError handling

Author: uranusjr

src/pip/_internal/resolution/resolvelib/candidates.py

@@ -221,6 +221,9 @@ def _prepare(self):
         try:
             dist = self._prepare_distribution()
         except HashError as e:
+            # Provide HashError the underlying ireq that caused it. This
+            # provides context for the resulting error message to show the
+            # offending line to the user.
             e.req = self._ireq
             raise
         self._check_metadata_consistency(dist)

src/pip/_internal/resolution/resolvelib/factory.py

@@ -137,8 +137,12 @@ def _make_candidate_from_link(
         # type: (...) -> Optional[Candidate]
         # TODO: Check already installed candidate, and use it if the link and
         # editable flag match.
+
         if link in self._build_failures:
+            # We already tried this candidate before, and it does not build.
+            # Don't bother trying again.
             return None
+
         if template.editable:
             if link not in self._editable_candidate_cache:
                 try:
@@ -163,6 +167,7 @@ def _make_candidate_from_link(
                     self._build_failures[link] = e
                     return None
             base = self._link_candidate_cache[link]
+
         if extras:
             return ExtrasCandidate(base, extras)
         return base
@@ -296,6 +301,12 @@ def make_requirement_from_install_req(self, ireq, requested_extras):
             version=None,
         )
         if cand is None:
+            # There's no way we can satisfy a URL requirement if the underlying
+            # candidate fails to build. An unnamed URL must be user-supplied, so
+            # we fail eagerly. If the URL is named, an unsatisfiable requirement
+            # can make the resolver do the right thing, either backtrack (and
+            # maybe find some other requirement that's buildable) or raise a
+            # ResolutionImpossible eventually.
             if not ireq.name:
                 raise self._build_failures[ireq.link]
             return UnsatisfiableRequirement(canonicalize_name(ireq.name))