Apply suggestions from code review

Co-authored-by: Hilary James Oliver <[email protected]>

cylc/flow/cfgspec/workflow.py

@@ -997,13 +997,15 @@ def get_script_common_text(this: str, example: Optional[str] = None):
             settings for all tasks in the workflow.
         '''):
             Conf('completion', VDR.V_STRING, desc='''
-                Define the condition for task completion.
+                Define the condition for task output completion.
 
-                The completion condition is evaluated when a task finishes
-                executing. It is a validation check which confirms that the
+                The completion condition is evaluated when a task attains
+                a final status - i.e., once it finished executing (``succeeded``
+                or ``failed``) or it ``submit-failed``, or ``expired``.
+                It is a validation check which confirms that the
                 task has generated the outputs it was expected to.
 
-                If the task fails this check it's outputs are considered
+                If the task fails this check its outputs are considered
                 :term:`incomplete` and a warning will be raised alerting you
                 that something has gone wrong which requires investigation.
 
@@ -1017,7 +1019,7 @@ def get_script_common_text(this: str, example: Optional[str] = None):
                 marked as optional with the ``?`` character, are completed.
 
                 E.g., in this example, the task ``foo`` must generate the
-                required outputs ``succeeded`` and ``x``, it may or may not
+                required outputs ``succeeded`` and ``x`` and it may or may not
                 generate the optional output ``y``:
 
                 .. code-block:: cylc-graph
@@ -1030,13 +1032,13 @@ def get_script_common_text(this: str, example: Optional[str] = None):
 
                 .. code-block:: python
 
-                   # the task must succeeded and generate the custom output "x"
+                   # the task must succeed and generate the custom output "x"
                    succeeded and x
 
                 The ``completion`` configuration allows you to override the
                 default completion to suit your needs.
 
-                E.G., in this example, the task ``foo`` has three optional
+                E.g., in this example, the task ``foo`` has three optional
                 outputs, ``x``, ``y`` and ``z``:
 
                 .. code-block:: cylc-graph
@@ -1051,18 +1053,19 @@ def get_script_common_text(this: str, example: Optional[str] = None):
                 considered complete.
 
                 If you wanted to require that at least one of these outputs is
-                generated you could configure the completion confition like so:
+                generated you can configure the completion condition like so:
 
                 .. code-block:: python
 
-                   # the task must succeeded and generate at least one of the
+                   # the task must succeed and generate at least one of the
                    # outputs "x" or "y" or "z":
                    succeeded and (x or y or z)
 
                 .. note::
 
                    For the completion expression, hyphens in task outputs
-                   are converted into underscores e.g:
+                   are converted into underscores to allow
+                   evaluation by Python, e.g.:
 
                    .. code-block:: cylc
 

cylc/flow/task_outputs.py

@@ -102,7 +102,7 @@ def get_completion_expression(tdef: 'TaskDef') -> str:
 
     1. Create a completion expression that ensures all required ouputs are
        completed.
-    2. If succeess is optional add "or succeeded or failed" onto the end.
+    2. If success is optional add "or succeeded or failed" onto the end.
     3. If submission is optional add "or submit-failed" onto the end of it.
     4. If expiry is optional add "or expired" onto the end of it.
     """
@@ -133,7 +133,7 @@ def get_completion_expression(tdef: 'TaskDef') -> str:
         tdef.outputs[TASK_OUTPUT_SUCCEEDED][1] is False
         or tdef.outputs[TASK_OUTPUT_FAILED][1] is False
     ):
-        # failure is tolerated -> ensure the task succeess OR fails
+        # failure is tolerated -> ensure the task succeeds OR fails
         if required:
             # required outputs are required only if the task actually runs
             parts = [
@@ -205,7 +205,7 @@ def get_optional_outputs(
     # determine which triggers are used in the expression
     used_compvars = get_variable_names(expression)
 
-    # all completion vairables which could appear in the expression
+    # all completion variables which could appear in the expression
     all_compvars = {trigger_to_completion_variable(out) for out in outputs}
 
     return {  # output: is_optional
@@ -306,7 +306,7 @@ def set_message_complete(self, message):
         if (
             # Note, this interface sometimes gets called erroneously, so we
             # have to check that the message being set actually applies to
-            # these outputs before setting it
+            # these outputs before setting it.
             message in self._completed
             and self._completed[message] is False
         ):
@@ -315,7 +315,7 @@ def set_message_complete(self, message):
         return False
 
     def is_message_complete(self, message: str) -> Optional[bool]:
-        """Return True if this messages is complete.
+        """Return True if this message is complete.
 
         Returns:
             * True if the message is complete.