lua: make hook processing more flexible

This can now opt to not continue a hook after the hook callback returns.
This makes it easier for scripts, and may make it unnecessary to run
reentrant event loops etc. for scripts that want to wait before
continuing while still running the event loop.

1 files changed, 16 insertions, 2 deletions

diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst
index 88fb4cb7ce..3fdb0b2f42 100644
--- a/DOCS/man/lua.rst
+++ b/DOCS/man/lua.rst
@@ -889,8 +889,22 @@ guarantee a stable interface.
     their result (normally, the Lua scripting interface is asynchronous from
     the point of view of the player core). ``priority`` is an arbitrary integer
     that allows ordering among hooks of the same kind. Using the value 50 is
-    recommended as neutral default value. ``fn`` is the function that will be
-    called during execution of the hook.
+    recommended as neutral default value.
+
+    ``fn(hook)`` is the function that will be called during execution of the
+    hook. The parameter passed to it (``hook``) is a Lua object that can control
+    further aspects about the currently invoked hook. It provides the following
+    methods:
+
+        ``defer()``
+            Returning from the hook function should not automatically continue
+            the hook. Instead, the API user wants to call ``hook:cont()`` on its
+            own at a later point in time (before or after the function has
+            returned).
+
+        ``cont()``
+            Continue the hook. Doesn't need to be called unless ``defer()`` was
+            called.
 
     See `Hooks`_ for currently existing hooks and what they do - only the hook
     list is interesting; handling hook execution is done by the Lua script