diff --git a/docs/compat.dox b/docs/compat.dox
index 59530b73..da3dbfb0 100644
--- a/docs/compat.dox
+++ b/docs/compat.dox
@@ -101,6 +101,15 @@ GLFW uses xkbcommon 0.5.0 to provide compose key support.  When it has been
 built against an older xkbcommon, the compose key will be disabled even if it
 has been configured in the compositor.
 
+GLFW uses the [xdg-shell
+protocol](https://cgit.freedesktop.org/wayland/wayland-protocols/tree/stable/xdg-shell/xdg-shell.xml)
+to provide better window management.  This protocol is part of
+wayland-protocols 1.12, and mandatory at build time.  If the running compositor
+does not support this protocol, the older [wl_shell
+interface](https://cgit.freedesktop.org/wayland/wayland/tree/protocol/wayland.xml#n972)
+will be used instead.  This will result in a worse integration with the
+desktop, especially on tiling compositors.
+
 GLFW uses the [relative pointer
 protocol](https://cgit.freedesktop.org/wayland/wayland-protocols/tree/unstable/relative-pointer/relative-pointer-unstable-v1.xml)
 alongside the [pointer constraints
diff --git a/include/GLFW/glfw3.h b/include/GLFW/glfw3.h
index 9b21de7d..dbb1429e 100644
--- a/include/GLFW/glfw3.h
+++ b/include/GLFW/glfw3.h
@@ -2459,10 +2459,6 @@ GLFWAPI void glfwWindowHintString(int hint, const char* value);
  *  @remark @wayland A full screen window will not attempt to change the mode,
  *  no matter what the requested size or refresh rate.
  *
- *  @remark @wayland The wl_shell protocol does not support window
- *  icons, the window will inherit the one defined in the application's
- *  desktop file, so this function emits @ref GLFW_PLATFORM_ERROR.
- *
  *  @remark @wayland Screensaver inhibition requires the idle-inhibit protocol
  *  to be implemented in the user's compositor.
  *
@@ -2606,9 +2602,9 @@ GLFWAPI void glfwSetWindowTitle(GLFWwindow* window, const char* title);
  *  [Bundle Programming Guide](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/)
  *  in the Mac Developer Library.
  *
- *  @remark @wayland The wl_shell protocol does not support icons, the window
- *  will inherit the one defined in the application's desktop file, so this
- *  function emits @ref GLFW_PLATFORM_ERROR.
+ *  @remark @wayland There is no existing protocol to change an icon, the
+ *  window will thus inherit the one defined in the application's desktop file.
+ *  This function always emits @ref GLFW_PLATFORM_ERROR.
  *
  *  @thread_safety This function must only be called from the main thread.
  *
@@ -3016,7 +3012,8 @@ GLFWAPI void glfwSetWindowOpacity(GLFWwindow* window, float opacity);
  *  GLFW_PLATFORM_ERROR.
  *
  *  @remark @wayland There is no concept of iconification in wl_shell, this
- *  function will always emit @ref GLFW_PLATFORM_ERROR.
+ *  function will emit @ref GLFW_PLATFORM_ERROR when using this deprecated
+ *  protocol.
  *
  *  @thread_safety This function must only be called from the main thread.
  *
@@ -3541,7 +3538,7 @@ GLFWAPI GLFWwindowfocusfun glfwSetWindowFocusCallback(GLFWwindow* window, GLFWwi
  *  @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
  *
  *  @remark @wayland The wl_shell protocol has no concept of iconification,
- *  this callback will never be called.
+ *  this callback will never be called when using this deprecated protocol.
  *
  *  @thread_safety This function must only be called from the main thread.
  *