main loop: document coroutine types

cylc/flow/main_loop/__init__.py

@@ -133,21 +133,69 @@ def _debounce(interval, timings):
 
 
 def startup(fcn):
+    """Decorates a coroutine which is run at suite startup.
+
+    The decorated coroutine should have the signature:
+
+        async coroutine(scheduler, plugin_state) -> None
+
+    Exceptions:
+
+        * Regular Exceptions are caught and logged.
+        * Exceptions which subclass CylcError are re-raised as
+          MainLoopPluginException
+
+    """
     fcn.main_loop = CoroTypes.StartUp
     return fcn
 
 
 def shutdown(fcn):
+    """Decorates a coroutine which is run at suite shutdown.
+
+    Note shutdown refers to "clean" shutdown as opposed to suite abort.
+
+    The decorated coroutine should have the signature:
+
+        async coroutine(scheduler, plugin_state) -> None
+
+    Exceptions:
+
+        * Regular Exceptions are caught and logged.
+        * Exceptions which subclass CylcError are re-raised as
+          MainLoopPluginException
+
+    """
     fcn.main_loop = CoroTypes.ShutDown
     return fcn
 
 
 def periodic(fcn):
+    """Decorates a coroutine which is run at a set interval.
+
+    The decorated coroutine should have the signature:
+
+        async coroutine(scheduler, plugin_state) -> None
+
+    Exceptions:
+
+        * Regular Exceptions are caught and logged.
+        * Exceptions which subclass CylcError are re-raised as
+          MainLoopPluginException
+
+    Configuration:
+
+        * The interval of execution can be altered using the
+          `cylc[main loop][plugin name]interval` setting.
+
+    """
     fcn.main_loop = CoroTypes.Periodic
     return fcn
 
 
 class CoroTypes:
+    """Different types of coroutine which can be used with the main loop."""
+
     StartUp = startup
     ShutDown = shutdown
     Periodic = periodic