document the map/unmap xdg-shell events

2 files changed, 42 insertions, 0 deletions

diff --git a/include/wlr/types/wlr_xdg_shell.h b/include/wlr/types/wlr_xdg_shell.h
index 11709c75..8b9980ad 100644
--- a/include/wlr/types/wlr_xdg_shell.h
+++ b/include/wlr/types/wlr_xdg_shell.h
@@ -14,6 +14,13 @@ struct wlr_xdg_shell {
 	struct wl_listener display_destroy;
 
 	struct {
+		/**
+		 * The `new_surface` event signals that a client has requested to
+		 * create a new shell surface. At this point, the surface is ready to
+		 * be configured but not ready to be managed by the compositor by
+		 * adding it to a list of views. The surface will be ready to be
+		 * managed on the `map` event.
+		 */
 		struct wl_signal new_surface;
 	} events;
 
@@ -162,7 +169,21 @@ struct wlr_xdg_surface {
 		struct wl_signal destroy;
 		struct wl_signal ping_timeout;
 		struct wl_signal new_popup;
+		/**
+		 * The `map` event signals that the shell surface is ready to be
+		 * managed by the compositor and rendered on the screen. At this point,
+		 * the surface has configured its properties, has had the opportunity
+		 * to bind to the seat to receive input events, and has a buffer that
+		 * is ready to be rendered. You can now safely add this surface to a
+		 * list of views.
+		 */
 		struct wl_signal map;
+		/**
+		 * The `unmap` event signals that the surface is no longer in a state
+		 * where it should be shown on the screen. This might happen if the
+		 * surface no longer has a displayable buffer because either the
+		 * surface has been hidden or is about to be destroyed.
+		 */
 		struct wl_signal unmap;
 	} events;
 
diff --git a/include/wlr/types/wlr_xdg_shell_v6.h b/include/wlr/types/wlr_xdg_shell_v6.h
index bce645da..34bf77b1 100644
--- a/include/wlr/types/wlr_xdg_shell_v6.h
+++ b/include/wlr/types/wlr_xdg_shell_v6.h
@@ -15,6 +15,13 @@ struct wlr_xdg_shell_v6 {
 	struct wl_listener display_destroy;
 
 	struct {
+		/**
+		 * The `new_surface` event signals that a client has requested to
+		 * create a new shell surface. At this point, the surface is ready to
+		 * be configured but not ready to be managed by the compositor by
+		 * adding it to a list of views. The surface will be ready to be
+		 * managed on the `map` event.
+		 */
 		struct wl_signal new_surface;
 	} events;
 
@@ -160,7 +167,21 @@ struct wlr_xdg_surface_v6 {
 		struct wl_signal destroy;
 		struct wl_signal ping_timeout;
 		struct wl_signal new_popup;
+		/**
+		 * The `map` event signals that the shell surface is ready to be
+		 * managed by the compositor and rendered on the screen. At this point,
+		 * the surface has configured its properties, has had the opportunity
+		 * to bind to the seat to receive input events, and has a buffer that
+		 * is ready to be rendered. You can now safely add this surface to a
+		 * list of views.
+		 */
 		struct wl_signal map;
+		/**
+		 * The `unmap` event signals that the surface is no longer in a state
+		 * where it should be shown on the screen. This might happen if the
+		 * surface no longer has a displayable buffer because either the
+		 * surface has been hidden or is about to be destroyed.
+		 */
 		struct wl_signal unmap;
 	} events;