diff --git a/doc/publican/sources/Protocol.xml b/doc/publican/sources/Protocol.xml
index 97e9ba29..a88d50ca 100644
--- a/doc/publican/sources/Protocol.xml
+++ b/doc/publican/sources/Protocol.xml
@@ -92,9 +92,12 @@
     <title>Wire Format</title>
     <para>
       The protocol is sent over a UNIX domain stream socket, where the endpoint
-      usually is named <systemitem class="service">wayland-0</systemitem>
-      (although it can be changed via <emphasis>WAYLAND_DISPLAY</emphasis>
-      in the environment). Beginning in Wayland 1.15, implementations can
+      is specified by the environment variable <emphasis>WAYLAND_DISPLAY</emphasis>.
+      (For compatibility reasons, if this environment variable is not set,
+      clients may try to connect to socket <systemitem class="service">wayland-0</systemitem>.
+      As this behavior may lead to accidental connections,
+      compositors are recommended never to set  <emphasis>WAYLAND_DISPLAY</emphasis>
+      to this value.) Beginning in Wayland 1.15, implementations can
       optionally support server socket endpoints located at arbitrary
       locations in the filesystem by setting <emphasis>WAYLAND_DISPLAY</emphasis>
       to the absolute path at which the server endpoint listens.
diff --git a/src/wayland-client.c b/src/wayland-client.c
index 21d46067..2aa745fc 100644
--- a/src/wayland-client.c
+++ b/src/wayland-client.c
@@ -1111,7 +1111,8 @@ wl_display_connect_to_fd(int fd)
  *
  * Connect to the Wayland display named \c name. If \c name is \c NULL,
  * its value will be replaced with the WAYLAND_DISPLAY environment
- * variable if it is set, otherwise display "wayland-0" will be used.
+ * variable if it is set. For compatibility reasons, if WAYLAND_DISPLAY
+ * is not set, the value "wayland-0" will be used.
  *
  * If WAYLAND_SOCKET is set, it's interpreted as a file descriptor number
  * referring to an already opened socket. In this case, the socket is used
diff --git a/src/wayland-server.c b/src/wayland-server.c
index d83bdecd..c8338a71 100644
--- a/src/wayland-server.c
+++ b/src/wayland-server.c
@@ -1549,6 +1549,41 @@ _wl_display_add_socket(struct wl_display *display, struct wl_socket *s)
 	return 0;
 }
 
+/** Automatically pick a Wayland display socket for the clients to connect to.
+ *
+ * \param display Wayland display to which the socket should be added.
+ * \return The socket name if success. NULL if failed.
+ *
+ * This function is equivalent to calling, for %d ranging from 0 to 32,
+ * the function:
+ *
+ * \code{.c}
+ *     wl_display_add_socket(display, "wayland-%d")
+ * \endcode
+ *
+ * and returning the name of the new socket as soon as a call succeeds.
+ * The string returned should not be modified or freed.
+ *
+ * Because this function first tries to register the Wayland display
+ * socket name "wayland-0", and clients (for compatibility reasons) try
+ * to connect to "wayland-0" if the environment variable WAYLAND_DISPLAY
+ * is not set, clients may connect by accident. As a result, this function
+ * is NOT recommended. Instead, compositors should explicitly
+ * try socket names starting at e.g. wayland-1; for example:
+ *
+ * \code{.c}
+ *    for (int i = 1; i <= 32; i++) {
+ *       char display_name[16] = "";
+ *       snprintf(display_name, sizeof display_name, "wayland-%d", i);
+ *       if (wl_display_add_socket(display, display_name) == 0) {
+ *          return strdup(display_name);
+ *       }
+ *    }
+ *    return NULL;
+ * \endcode
+ *
+ * \memberof wl_display
+ */
 WL_EXPORT const char *
 wl_display_add_socket_auto(struct wl_display *display)
 {
@@ -1643,7 +1678,13 @@ wl_display_add_socket_fd(struct wl_display *display, int sock_fd)
  *
  * If NULL is passed as name, then it would look for WAYLAND_DISPLAY env
  * variable for the socket name. If WAYLAND_DISPLAY is not set, then default
- * wayland-0 is used.
+ * wayland-0 is used. This fallback, kept for compatibility reasons,
+ * has two problems: 1) most clients will by default connect to wayland-0
+ * if their environment does not contain WAYLAND_DISPLAY, and thus may
+ * connect to this socket by accident when run outside of a GUI; 2) some
+ * clients do not by default connect to wayland-0, and always require
+ * WAYLAND_DISPLAY to be set. Consequently, passing NULL in as an argument
+ * to this function is not recommended.
  *
  * If the socket name is a relative path, the Unix socket will be created in
  * the directory pointed to by environment variable XDG_RUNTIME_DIR. If