doc: clarify "server state" and "client state" distinction

Add a common page for the concept and link to there from the relevant
functions.

Signed-off-by: Ran Benita <ran@unusedvar.com>

include/xkbcommon/xkbcommon.h

@@ -1342,6 +1342,33 @@ xkb_state_unref(struct xkb_state *state);
 struct xkb_keymap *
 xkb_state_get_keymap(struct xkb_state *state);
 
+/**
+ * @page server-client-state Server State and Client State
+ * @parblock
+ *
+ * The xkb_state API is used by two distinct actors in most window-system
+ * architectures:
+ *
+ * 1. A *server* - for example, a Wayland compositor, an X11 server, an evdev
+ *    listener.
+ *
+ *    Servers maintain the XKB state for a device according to input events from
+ *    the device, such as key presses and releases, and out-of-band events from
+ *    the user, like UI layout switchers.
+ *
+ * 2. A *client* - for example, a Wayland client, an X11 client.
+ *
+ *    Clients do not listen to input from the device; instead, whenever the
+ *    server state changes, the server serializes the state and notifies the
+ *    clients that the state has changed; the clients then update the state
+ *    from the serialization.
+ *
+ * Some entry points in the xkb_state API are only meant for servers and some
+ * are only meant for clients, and the two should generally not be mixed.
+ *
+ * @endparblock
+ */
+
 /** Specifies the direction of the key (press / release). */
 enum xkb_key_direction {
     XKB_KEY_UP,   /**< The key was released. */
@@ -1388,11 +1415,8 @@ enum xkb_state_component {
  * Update the keyboard state to reflect a given key being pressed or
  * released.
  *
- * This entry point is intended for programs which track the keyboard state
- * explicitly (like an evdev client).  If the state is serialized to you by
- * a master process (like a Wayland compositor) using functions like
- * xkb_state_serialize_mods(), you should use xkb_state_update_mask() instead.
- * The two functions should not generally be used together.
+ * This entry point is intended for *server* applications and should not be used
+ * by *client* applications; see @ref server-client-state for details.
  *
  * A series of calls to this function should be consistent; that is, a call
  * with XKB_KEY_DOWN for a key should be matched by an XKB_KEY_UP; if a key
@@ -1420,21 +1444,16 @@ xkb_state_update_key(struct xkb_state *state, xkb_keycode_t key,
 /**
  * Update a keyboard state from a set of explicit masks.
  *
- * This entry point is intended for window systems and the like, where a
- * master process holds an xkb_state, then serializes it over a wire
- * protocol, and clients then use the serialization to feed in to their own
- * xkb_state.
+ * This entry point is intended for *client* applications; see @ref
+ * server-client-state for details. *Server* applications should use
+ * xkb_state_update_key() instead.
  *
  * All parameters must always be passed, or the resulting state may be
  * incoherent.
  *
  * The serialization is lossy and will not survive round trips; it must only
- * be used to feed slave state objects, and must not be used to update the
- * master state.
- *
- * If you do not fit the description above, you should use
- * xkb_state_update_key() instead.  The two functions should not generally be
- * used together.
+ * be used to feed client state objects, and must not be used to update the
+ * server state.
  *
  * @returns A mask of state components that have changed as a result of
  * the update.  If nothing in the state has changed, returns 0.
@@ -1612,6 +1631,10 @@ enum xkb_state_match {
  * The counterpart to xkb_state_update_mask for modifiers, to be used on
  * the server side of serialization.
  *
+ * This entry point is intended for *server* applications; see @ref
+ * server-client-state for details. *Client* applications should use the
+ * xkb_state_mod_*_is_active API.
+ *
  * @param state      The keyboard state.
  * @param components A mask of the modifier state components to serialize.
  * State components other than XKB_STATE_MODS_* are ignored.
@@ -1621,9 +1644,6 @@ enum xkb_state_match {
  * @returns A xkb_mod_mask_t representing the given components of the
  * modifier state.
  *
- * This function should not be used in regular clients; please use the
- * xkb_state_mod_*_is_active API instead.
- *
  * @memberof xkb_state
  */
 xkb_mod_mask_t
@@ -1634,6 +1654,10 @@ xkb_state_serialize_mods(struct xkb_state *state,
  * The counterpart to xkb_state_update_mask for layouts, to be used on
  * the server side of serialization.
  *
+ * This entry point is intended for *server* applications; see @ref
+ * server-client-state for details. *Client* applications should use the
+ * xkb_state_layout_*_is_active API.
+ *
  * @param state      The keyboard state.
  * @param components A mask of the layout state components to serialize.
  * State components other than XKB_STATE_LAYOUT_* are ignored.
@@ -1643,9 +1667,6 @@ xkb_state_serialize_mods(struct xkb_state *state,
  * @returns A layout index representing the given components of the
  * layout state.
  *
- * This function should not be used in regular clients; please use the
- * xkb_state_layout_*_is_active API instead.
- *
  * @memberof xkb_state
  */
 xkb_layout_index_t