doc fixes

cylc/flow/network/schema.py

@@ -1286,15 +1286,9 @@ class Meta:
         description = sstrip(f'''
             Tell a suite server program to shut down.
 
-            In order to prevent failures going unnoticed, suites only shut down
-            automatically at a final cycle point if no failed tasks are
-            present. There are several shutdown methods:
-
-            Tasks that become ready after the shutdown is ordered will be
-            submitted immediately if the suite is restarted.  Remaining task
-            event handlers and job poll and kill commands, however, will be
-            executed prior to shutdown, unless the stop mode is
-            `{StopMode.REQUEST_NOW}`.
+            By default suites wait for all submitted and running tasks to
+            complete before shutting down. You can change this behaviour
+            with the "mode" option.
         ''')
         resolver = partial(mutator, command='stop_workflow')
 
@@ -1459,7 +1453,7 @@ class Meta:
             Remove one or more task instances from a running workflow.
 
             Tasks will be forced to spawn successors before removal if they
-            have not done so already, unless you use `no_spawn`.
+            have not done so already, unless you change the `spawn` option.
         ''')
         resolver = partial(mutator, command='remove_tasks')
 
@@ -1477,7 +1471,7 @@ class Meta:
 
             Outputs are automatically updated to reflect the new task state,
             except for custom message outputs which can be manipulated directly
-            with `output`.
+            with `outputs`.
 
             Prerequisites reflect the state of other tasks; they are not
             changed except to unset them on resetting state to

cylc/flow/network/server.py

@@ -326,7 +326,8 @@ def broadcast(
         if mode == 'clear_broadcast':
             return self.schd.task_events_mgr.broadcast_mgr.clear_broadcast(
                 cycle_points, tasks, settings)
-        raise ValueError('TEMP: TODO: FixMe!')
+        # TODO implement other broadcast interfaces (i.e. expire, display)
+        raise ValueError('Unsupported broadcast mode')
 
     @authorise(Priv.READ)
     @expose
@@ -412,7 +413,7 @@ def dry_run_tasks(self, tasks, check_syntax=True):
         """Prepare job file for a task.
 
         Args:
-            task_globs (list): List of identifiers, see `task globs`_
+            task (list): List of identifiers, see `task globs`_
             check_syntax (bool, optional): Check shell syntax.
 
         Returns:
@@ -755,9 +756,9 @@ def insert_tasks(self, tasks, stop_point=None, check_point=True):
                 any glob characters (``*``).
             stop_point (str, optional):
                 Optional hold/stop cycle point for inserted task.
-            no_check (bool, optional):
-                Add task even if the provided cycle point is not valid
-                for the given task.
+            check_point (bool, optional):
+                If True check that the cycle point is valid for the
+                given task and fail if it is not.
         Returns:
             tuple: (outcome, message)
 
@@ -863,7 +864,7 @@ def poll_tasks(self, tasks=None, poll_succeeded=False):
         Args:
             tasks (list, optional):
                 List of identifiers, see `task globs`_
-            poll_succ (bool, optional):
+            poll_succeeded (bool, optional):
                 Allow polling of remote tasks if True.
 
         Returns:

cylc/flow/suite_status.py

@@ -78,11 +78,23 @@ def describe(self):
         if self == self.AUTO_ON_TASK_FAILURE:
             return 'Wait until the first task fails.'
         if self == self.REQUEST_CLEAN:
-            return 'Wait for active jobs to complete.'
+            return (
+                'Regular shutdown:\n'
+                '* Wait for all active jobs to complete.\n'
+                '* Run suite event handlers and wait for them to complete.'
+            )
         if self == self.REQUEST_NOW:
-            return 'Immediate shutdown, wait for event handlers to complete.'
+            return (
+                'Immediate shutdown\n'
+                "* Don't kill submitted or running jobs.\n"
+                '* Run suite event handlers and wait for them to complete.'
+            )
         if self == self.REQUEST_NOW_NOW:
-            return 'Immediate shutdown.'
+            return (
+                'Immediate shutdown\n'
+                "* Don't kill submitted or running jobs.\n"
+                "* Don't run event handlers."
+            )
         return ''