From d8f4749c341e855c9da4569248f2d61b8cd3c7f1 Mon Sep 17 00:00:00 2001
From: gaesa <71256557+gaesa@users.noreply.github.com>
Date: Sat, 10 Feb 2024 17:37:41 +0800
Subject: [PATCH] DOCS/lua: clarify `repeatable` and `complex` for
 `add_key_binding`

The current documentation lacks clarity regarding the interaction
between the `repeatable` and `complex` options. Through an analysis
of the source code (`player/lua/defaults.lua` and
`player/js/defaults.js`), it was observed that the `repeatable` option
is only meaningful when the `complex` option is not enabled.
Additionally, the `complex` option in the existing documentation is
confusing, actually `fn` can be called on key repeat when `complex` is
`true` and `repeatable` is not `true`.

To address these issues, the documentation for the `repeatable` option
was updated to specify that it only applies when the `complex` option is
not set to `true`. Furthermore, the description of the `complex` and
`event` were revised to acknowledge the occurrence of key repeat events.
---
 DOCS/man/lua.rst | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst
index 6a18e60e1d..73776964d5 100644
--- a/DOCS/man/lua.rst
+++ b/DOCS/man/lua.rst
@@ -308,16 +308,17 @@ The ``mp`` module is preloaded, although it can be loaded manually with
 
         ``repeatable``
             If set to ``true``, enables key repeat for this specific binding.
+            This option only makes sense when ``complex`` is not set to ``true``.
 
         ``complex``
-            If set to ``true``, then ``fn`` is called on both key up and down
-            events (as well as key repeat, if enabled), with the first
-            argument being a table. This table has the following entries (and
-            may contain undocumented ones):
+            If set to ``true``, then ``fn`` is called on key down, repeat and up
+            events, with the first argument being a table. This table has the
+            following entries (and may contain undocumented ones):
 
                 ``event``
                     Set to one of the strings ``down``, ``repeat``, ``up`` or
-                    ``press`` (the latter if key up/down can't be tracked).
+                    ``press`` (the latter if key up/down/repeat can't be
+                    tracked).
 
                 ``is_mouse``
                     Boolean Whether the event was caused by a mouse button.