Clean up and document

python/lsst/ctrl/mpexec/cli/cmd/commands.py

@@ -388,24 +388,25 @@ def report(
 ) -> None:
     """Summarize the state of executed quantum graph(s), with counts of failed,
     successful and expected quanta, as well as counts of output datasets and
-    their publish states. Analyze one or more attempts at the same
-    processing on the same dataquery-identified "group" and resolve recoveries
-    and persistent failures. Identify mismatch errors between groups.
+    their query (visible/shadowed) states. Analyze one or more attempts at the
+    same processing on the same dataquery-identified "group" and resolve
+    recoveries and persistent failures. Identify mismatch errors between
+    attempts.
 
     Save the report as a file (`--full-output-filename`) or print it to stdout
     (default). If the terminal is overwhelmed with data_ids from failures try
     the `--brief` option.
 
     Butler `collections` and `where` options are for use in
     `lsst.daf.butler.queryDatasets` if paring down the collections would be
-    useful. By default the collections and query will match the graphs.
+    useful. By default the collections and query be taken from the graphs.
 
     REPO is the location of the butler/registry config file.
 
-    QGRAPHS is a Sequence of links to serialized Quantum Graphs which have been
-    executed and are to be analyzed.
+    QGRAPHS is a `Sequence` of links to serialized Quantum Graphs which have
+    been executed and are to be analyzed.
     """
-    if force_v2 or len(qgraphs) > 1 or collections:
+    if any([force_v2, len(qgraphs) > 1, collections, where, curse_failed_logs]):
         script.report_v2(
             repo, qgraphs, collections, where, full_output_filename, logs, brief, curse_failed_logs
         )

python/lsst/ctrl/mpexec/cli/script/report.py

@@ -42,7 +42,8 @@ def report(
     brief: bool = False,
 ) -> None:
     """Summarize the produced, missing and expected quanta and
-    datasets belonging to an executed quantum graph.
+    datasets belonging to an executed quantum graph using the
+    `QuantumGraphExecutionReport`.
 
     Parameters
     ----------
@@ -126,7 +127,7 @@ def report_v2(
 ) -> None:
     """Summarize the state of executed quantum graph(s), with counts of failed,
     successful and expected quanta, as well as counts of output datasets and
-    their publish states. Analyze one or more attempts at the same
+    their visible/shadowed states. Analyze one or more attempts at the same
     processing on the same dataquery-identified "group" and resolve recoveries
     and persistent failures. Identify mismatch errors between groups.
 
@@ -162,9 +163,10 @@ def report_v2(
             Mark log datasets as `cursed` if they are published in the final
             output collection. Note that a campaign-level collection must be
             used here for `collections` if `curse_failed_logs` is `True`; if
-            `resolve_duplicates` is run on a list of group-level collections
-            then each will show logs from their own failures as published
-            the datasets will show as cursed regardless of this flag.
+            `lsst.pipe.base.QuantumProvenanceGraph.__resolve_duplicates`
+            is run on a list of group-level collections, then each will only
+            show log datasets from their own failures as visible and datasets
+            from others will be marked as cursed.
     """
     butler = Butler.from_config(butler_config, writeable=False)
     qpg = QuantumProvenanceGraph()
@@ -181,7 +183,7 @@ def print_summary(summary: Summary, full_output_filename: str | None, brief: boo
     Parameters
     ----------
     summary : `QuantumProvenanceGraph.Summary`
-            This object contains all the information derived from the
+            This `Pydantic` model contains all the information derived from the
             `QuantumProvenanceGraph`.
     full_output_filename : `str | None`
             Name of the JSON file in which to store summary information, if