doc: improve the description of the consumed modifier modes

Hopefully it is more understandable now.

https://bugs.freedesktop.org/show_bug.cgi?id=104768

Reported-by: Gatis Paeglis <gatis.paeglis@qt.io>
Signed-off-by: Ran Benita <ran234@gmail.com>

diff --git a/xkbcommon/xkbcommon.h b/xkbcommon/xkbcommon.h
index f217471..c28123f 100644 (file)
--- a/xkbcommon/xkbcommon.h
+++ b/xkbcommon/xkbcommon.h
@@ -1703,7 +1703,7 @@ enum xkb_consumed_mode {
     /**
      * This is the mode defined in the XKB specification and used by libX11.
      *
-     * A modifier is consumed iff it *may affect* key translation.
+     * A modifier is consumed if and only if it *may affect* key translation.
      *
      * For example, if `Control+Alt+<Backspace>` produces some assigned keysym,
      * then when pressing just `<Backspace>`, `Control` and `Alt` are consumed,
@@ -1714,16 +1714,17 @@ enum xkb_consumed_mode {
     /**
      * This is the mode used by the GTK+ toolkit.
      *
-     * The mode consists of the following two heuristics:
+     * The mode consists of the following two independent heuristics:
      *
-     * - The active set of modifiers, excluding modifiers which do not affect
-     *   the key (as described above), are considered consumed, if they result
-     *   in different keysyms being produced than when no modifiers are active.
-     *
-     * - Additionally, a single modifier is considered consumed if, were it the
-     *   only active modifier affecting the key (as described above), it would
-     *   result in different keysyms being produced than when no modifiers are
+     * - The currently active set of modifiers, excluding modifiers which do
+     *   not affect the key (as described for @ref XKB_CONSUMED_MODE_XKB), are
+     *   considered consumed, if the keysyms produced when all of them are
+     *   active are different from the keysyms produced when no modifiers are
      *   active.
+     *
+     * - A single modifier is considered consumed if the keysyms produced for
+     *   the key when it is the only active modifier are different from the
+     *   keysyms produced when no modifiers are active.
      */
     XKB_CONSUMED_MODE_GTK
 };