doc: demote the socket backend in the documentation

The socket backend is useful for debugging and testing but not for real
user-cases where the fd negotiation should be handled by the caller
(e.g. passing it down through the portal). Let's demote the socket
backend in favour of the fd backend.

Related https://gitlab.freedesktop.org/libinput/libei/-/issues/63

src/libei.h

@@ -542,7 +542,7 @@ ei_new(void *user_data);
  * receive events.
  *
  * A context supports exactly one backend, set up with one of
- * ei_setup_backend_socket() or ei_setup_backend_fd().
+ * ei_setup_backend_fd() or ei_setup_backend_socket().
  *
  * @param user_data An opaque pointer to be returned with ei_get_user_data()
  *
@@ -562,7 +562,7 @@ ei_new_sender(void *user_data);
  * send events.
  *
  * A context supports exactly one backend, set up with one of
- * ei_setup_backend_socket() or ei_setup_backend_fd().
+ * ei_setup_backend_fd() or ei_setup_backend_socket().
  *
  * @param user_data An opaque pointer to be returned with ei_get_user_data()
  *
@@ -720,17 +720,48 @@ ei_clock_set_now_func(struct ei *, ei_clock_now_func func);
  * the EIS implementation.
  *
  * This function must be called immediately after ei_new() and before
- * setting up a backend with ei_setup_backend_socket() or
- * ei_setup_backend_fd().
+ * setting up a backend with ei_setup_backend_fd() or
+ * ei_setup_backend_socket().
  */
 void
 ei_configure_name(struct ei * ei, const char *name);
 
+/**
+ * Initialize the ei context on the given socket file descriptor.
+ * The ei context will initiate the conversation with the EIS server listening
+ * on the other end of this socket.
+ *
+ * This is the preferred entry point for libei and should be the default
+ * used in new clients. It allows for private-by-default socket file descriptors
+ * and the policy on how the socket is created is delegated to the caller.
+ *
+ * If the connection was successful, an event of type @ref EI_EVENT_CONNECT
+ * or @ref EI_EVENT_DISCONNECT will become available after a future call to
+ * ei_dispatch().
+ *
+ * If the connection failed, use ei_unref() to release the data allocated
+ * for this context.
+ *
+ * This function takes ownership of the file descriptor, and will close it
+ * when tearing down.
+ *
+ * @return zero on success or a negative errno on failure
+ */
+int
+ei_setup_backend_fd(struct ei *ei, int fd);
+
 /**
  * Set this ei context to use the socket backend. The ei context will
  * connect to the socket at the given path and initiate the conversation
  * with the EIS server listening on that socket.
  *
+ * @note This backend requires the socket to be accessible
+ * to connect to and forces the EIS implementation to to identification and
+ * access control for clients. In almost all cases, the EIS implementation
+ * should use pre-created fds per client and the client should instead use
+ * ei_setup_backend_fd(). This backend is primarily useful for testing and
+ * debugging.
+ *
  * If @a socketpath is `NULL`, the value of the environment variable
  * `LIBEI_SOCKET` is used. If @a socketpath does not start with '/', it is
  * relative to `$XDG_RUNTIME_DIR`. If `XDG_RUNTIME_DIR` is not set, this
@@ -748,26 +779,6 @@ ei_configure_name(struct ei * ei, const char *name);
 int
 ei_setup_backend_socket(struct ei *ei, const char *socketpath);
 
-/**
- * Initialize the ei context on the given socket. The ei context will
- * initiate the conversation with the EIS server listening on the other end
- * of this socket.
- *
- * If the connection was successful, an event of type @ref EI_EVENT_CONNECT
- * or @ref EI_EVENT_DISCONNECT will become available after a future call to
- * ei_dispatch().
- *
- * If the connection failed, use ei_unref() to release the data allocated
- * for this context.
- *
- * This function takes ownership of the file descriptor, and will close it
- * when tearing down.
- *
- * @return zero on success or a negative errno on failure
- */
-int
-ei_setup_backend_fd(struct ei *ei, int fd);
-
 /**
  * libei keeps a single file descriptor for all events. This fd should be
  * monitored for events by the caller's mainloop, e.g. using select(). When

src/libeis.h

@@ -470,14 +470,12 @@ void
 eis_set_user_data(struct eis *eis, void *user_data);
 
 /**
- * Initialize the context with a UNIX socket name.
- * If the path does not start with / it is relative to $XDG_RUNTIME_DIR.
- */
-int
-eis_setup_backend_socket(struct eis *ctx, const char *path);
-
-/**
- * Initialize the context that can take pre-configured sockets.
+ * Initialize the context that can take pre-configured socket file descriptors,
+ * see eis_backend_fd_add_client().
+ *
+ * This is the preferred backend to use for EIS implementations as it keeps
+ * the file descriptors private for each client and is not subject to race
+ * conditions or unauthorized clients attempting to connect.
  */
 int
 eis_setup_backend_fd(struct eis *ctx);
@@ -490,6 +488,18 @@ eis_setup_backend_fd(struct eis *ctx);
 int
 eis_backend_fd_add_client(struct eis *ctx);
 
+/**
+ * Initialize the context with a UNIX socket name.
+ * If the path does not start with / it is relative to $XDG_RUNTIME_DIR.
+ *
+ * The socket will be accessible by any client with permissions to do so and
+ * it is up to the EIS implementation to authenticate clients. In almost
+ * all cases, the EIS implementation should use eis_setup_backend_fd() instead.
+ * This backend is primarily useful for testing and debugging.
+ */
+int
+eis_setup_backend_socket(struct eis *ctx, const char *path);
+
 /**
  * libeis keeps a single file descriptor for all events. This fd should be
  * monitored for events by the caller's mainloop, e.g. using select(). When