From adea8f84b6a25f7be18f9c66dcaf9a0c508ff69e Mon Sep 17 00:00:00 2001
From: Oliver Sanders <oliver.sanders@metoffice.gov.uk>
Date: Wed, 24 Apr 2024 11:09:58 +0100
Subject: [PATCH] xtriggers: docstring formatting fixes

---
 cylc/flow/xtriggers/echo.py           |  6 +++---
 cylc/flow/xtriggers/wall_clock.py     |  4 ++++
 cylc/flow/xtriggers/workflow_state.py |  1 +
 cylc/flow/xtriggers/xrandom.py        | 26 +++++++++++++-------------
 4 files changed, 21 insertions(+), 16 deletions(-)

diff --git a/cylc/flow/xtriggers/echo.py b/cylc/flow/xtriggers/echo.py
index d200e2389bb..83e6d66062f 100644
--- a/cylc/flow/xtriggers/echo.py
+++ b/cylc/flow/xtriggers/echo.py
@@ -30,6 +30,9 @@ def echo(*args, **kwargs) -> Tuple:
         *args: Print to stdout.
         **kwargs: Print to stdout, and return as output.
 
+    Returns:
+        (True/False, kwargs)
+
     Examples:
 
         >>> echo('Breakfast Time', succeed=True, egg='poached')
@@ -37,9 +40,6 @@ def echo(*args, **kwargs) -> Tuple:
         echo: KWARGS: {'succeed': True, 'egg': 'poached'}
         (True, {'succeed': True, 'egg': 'poached'})
 
-    Returns
-        (True/False, kwargs)
-
     """
     print("echo: ARGS:", args)
     print("echo: KWARGS:", kwargs)
diff --git a/cylc/flow/xtriggers/wall_clock.py b/cylc/flow/xtriggers/wall_clock.py
index 91ba49a8961..a159ec3019f 100644
--- a/cylc/flow/xtriggers/wall_clock.py
+++ b/cylc/flow/xtriggers/wall_clock.py
@@ -34,6 +34,10 @@ def wall_clock(offset: str = 'PT0S', sequential: bool = True):
             ISO 8601 interval to wait after the cycle point is reached in real
             time before triggering. May be negative, in which case it will
             trigger before the real time reaches the cycle point.
+        sequential:
+            Wall-clock xtriggers are run sequentially by default.
+            See :ref:`Sequential Xtriggers` for more details.
+
     """
     # NOTE: This is just a placeholder for the actual implementation.
     # This is only used for validating the signature and for autodocs.
diff --git a/cylc/flow/xtriggers/workflow_state.py b/cylc/flow/xtriggers/workflow_state.py
index 340f7bd51c1..76755085aa6 100644
--- a/cylc/flow/xtriggers/workflow_state.py
+++ b/cylc/flow/xtriggers/workflow_state.py
@@ -54,6 +54,7 @@ def workflow_state(
             The task status required for this xtrigger to be satisfied.
         message:
             The custom task output required for this xtrigger to be satisfied.
+
             .. note::
 
                This cannot be specified in conjunction with ``status``.
diff --git a/cylc/flow/xtriggers/xrandom.py b/cylc/flow/xtriggers/xrandom.py
index 867035d46f8..218470e4d12 100644
--- a/cylc/flow/xtriggers/xrandom.py
+++ b/cylc/flow/xtriggers/xrandom.py
@@ -45,6 +45,19 @@ def xrandom(
             Used to allow users to specialize the trigger with extra
             parameters.
 
+    Returns:
+        tuple: (satisfied, results)
+
+        satisfied:
+            True if ``satisfied`` else ``False``.
+        results:
+            A dictionary containing the following keys:
+
+            ``COLOR``
+                A random colour (e.g. red, orange, ...).
+            ``SIZE``
+                A random size (e.g. small, medium, ...).
+
     Examples:
         If the percent is zero, it returns that the trigger condition was
         not satisfied, and an empty dictionary.
@@ -74,19 +87,6 @@ def xrandom(
         >>> xrandom(99.99, 0)
         (True, {'COLOR': 'orange', 'SIZE': 'small'})
 
-    Returns:
-        tuple: (satisfied, results)
-
-        satisfied:
-            True if ``satisfied`` else ``False``.
-        results:
-            A dictionary containing the following keys:
-
-            ``COLOR``
-                A random colour (e.g. red, orange, ...).
-            ``SIZE``
-                A random size (e.g. small, medium, ...).
-
     """
     sleep(float(secs))
     results = {}