Make requirements on codegen products optional. (pantsbuild#6357)

We declare product requirements in various places to force
codegen to run before, e.g., dependency resolution.

However currently these requirements are mandatory, so
deregistering all codegen backends will cause the round engine
to find no producers of these products, and fail.

This commit changes these requirements to optional, so
that if there are no codegen backends, we don't attempt
to depend on their products.

Also, minor unrelated documentation nits that weren't worth a 
separate pull request.

src/python/pants/backend/jvm/tasks/coursier_resolve.py

@@ -661,8 +661,10 @@ def product_types(cls):
   @classmethod
   def prepare(cls, options, round_manager):
     super(CoursierResolve, cls).prepare(options, round_manager)
-    round_manager.require_data('java')
-    round_manager.require_data('scala')
+    # Codegen may inject extra resolvable deps, so make sure we have a product dependency
+    # on relevant codegen tasks, if any.
+    round_manager.optional_data('java')
+    round_manager.optional_data('scala')
 
   @classmethod
   def register_options(cls, register):

src/python/pants/backend/jvm/tasks/ivy_resolve.py

@@ -69,8 +69,10 @@ def product_types(cls):
   @classmethod
   def prepare(cls, options, round_manager):
     super(IvyResolve, cls).prepare(options, round_manager)
-    round_manager.require_data('java')
-    round_manager.require_data('scala')
+    # Codegen may inject extra resolvable deps, so make sure we have a product dependency
+    # on relevant codegen tasks, if any.
+    round_manager.optional_data('java')
+    round_manager.optional_data('scala')
 
   def __init__(self, *args, **kwargs):
     super(IvyResolve, self).__init__(*args, **kwargs)

src/python/pants/backend/python/tasks/gather_sources.py

@@ -40,7 +40,7 @@ def product_types(cls):
   @classmethod
   def prepare(cls, options, round_manager):
     round_manager.require_data(PythonInterpreter)
-    round_manager.require_data('python')  # For codegen.
+    round_manager.optional_data('python')  # For codegen.
 
   def execute(self):
     targets = self._collect_source_targets()

src/python/pants/backend/python/tasks/python_binary_create.py

@@ -51,8 +51,9 @@ def cache_target_dirs(self):
 
   @classmethod
   def prepare(cls, options, round_manager):
+    # See comment below for why we don't use the GatherSources.PYTHON_SOURCES product.
     round_manager.require_data(PythonInterpreter)
-    round_manager.require_data('python')  # For codegen.
+    round_manager.optional_data('python')  # For codegen.
     round_manager.optional_product(PythonRequirementLibrary)  # For local dists.
 
   @staticmethod

src/python/pants/backend/python/tasks/resolve_requirements_task_base.py

@@ -45,6 +45,9 @@ def _python_native_code_settings(self):
   def prepare(cls, options, round_manager):
     round_manager.require_data(PythonInterpreter)
     round_manager.optional_product(PythonRequirementLibrary)  # For local dists.
+    # Codegen may inject extra resolvable deps, so make sure we have a product dependency
+    # on relevant codegen tasks, if any.
+    round_manager.optional_data('python')
 
   def resolve_requirements(self, interpreter, req_libs):
     """Requirements resolution for PEX files.

src/python/pants/goal/run_tracker.py

@@ -163,6 +163,8 @@ def initialize(self):
       raise AssertionError('RunTracker.initialize must not be called multiple times.')
 
     # Initialize the run.
+
+    # Select a globally unique ID for the run, that sorts by time.
     millis = int((self._run_timestamp * 1000) % 1000)
     run_id = 'pants_run_{}_{}_{}'.format(
       time.strftime('%Y_%m_%d_%H_%M_%S', time.localtime(self._run_timestamp)),

src/python/pants/task/task.py

@@ -535,7 +535,7 @@ def check_artifact_cache(self, vts):
   def do_check_artifact_cache(self, vts, post_process_cached_vts=None):
     """Checks the artifact cache for the specified list of VersionedTargetSets.
 
-    Returns a pair (cached, uncached) of VersionedTargets that were
+    Returns a tuple (cached, uncached, uncached_causes) of VersionedTargets that were
     satisfied/unsatisfied from the cache.
     """
     if not vts: