Merge pull request #6553 from oliver-sanders/doc.comms-timeout

cli: correct --comms-timeout docs
cylc · Jan 13, 2025 · 0ba5275 · 0ba5275
2 parents 95f02cb + e8ce85a
commit 0ba5275
Show file tree

Hide file tree

Showing 2 changed files with 11 additions and 8 deletions.
diff --git a/cylc/flow/option_parsers.py b/cylc/flow/option_parsers.py
@@ -317,10 +317,13 @@ class CylcOptionParser(OptionParser):
         OptionSettings(
             ['--comms-timeout'], metavar='SEC',
             help=(
-                "Set a timeout for network connections"
-                " to the running workflow. The default is no timeout."
-                " For task messaging connections see"
-                " site/user config file documentation."
+                "Set the timeout for communication with the running workflow."
+                " The default is determined by the setup, 5 seconds for"
+                " TCP comms and 300 for SSH."
+                " If connections timeout, it likely means either, a complex"
+                " request has been issued (e.g. cylc tui); there is a network"
+                " issue; or a problem with the scheduler. Increasing the"
+                " timeout will help with the first case."
             ),
             action='store', default=None, dest='comms_timeout', useif='comms'),
         OptionSettings(

diff --git a/cylc/flow/scripts/tui.py b/cylc/flow/scripts/tui.py
@@ -65,10 +65,10 @@ def get_option_parser() -> COP:
         '--comms-timeout',
         metavar='SEC',
         help=(
-            "Set a timeout for network connections"
-            " to the running workflow. The default is 3 seconds."
-            " For task messaging connections see"
-            " site/user config file documentation."
+            # NOTE: Tui overrides the default client timeout
+            "Set the timeout for communication with the running workflow."
+            " The default is 3 seconds, uou may need to increase this in"
+            "order for Tui to keep up with especially busy workflows."
         ),
         action='store',
         default=3,