Document NULL return value of foo_from_wlr_surface() functions

wlr_xdg_surface_from_wlr_surface() for example may return NULL even if
the surface has the xdg surface role if the corresponding xdg surface
has been destroyed.

6 files changed, 55 insertions, 2 deletions

diff --git a/include/wlr/types/wlr_input_method_v2.h b/include/wlr/types/wlr_input_method_v2.h
index 316cecd5..8baeae57 100644
--- a/include/wlr/types/wlr_input_method_v2.h
+++ b/include/wlr/types/wlr_input_method_v2.h
@@ -122,9 +122,20 @@ void wlr_input_method_v2_send_done(struct wlr_input_method_v2 *input_method);
 void wlr_input_method_v2_send_unavailable(
 	struct wlr_input_method_v2 *input_method);
 
+/**
+ * Returns true if the surface has the input popup surface role.
+ */
 bool wlr_surface_is_input_popup_surface_v2(struct wlr_surface *surface);
+
+/**
+ * Get a struct wlr_input_popup_surface_v2 from a struct wlr_surface.
+ * Asserts that the surface has the input popup surface role.
+ * May return NULL even if the surface has the input popup surface role if the
+ * corresponding input popup surface has been destroyed.
+ */
 struct wlr_input_popup_surface_v2 *wlr_input_popup_surface_v2_from_wlr_surface(
 	struct wlr_surface *surface);
+
 void wlr_input_popup_surface_v2_send_text_input_rectangle(
     struct wlr_input_popup_surface_v2 *popup_surface, struct wlr_box *sbox);
 
diff --git a/include/wlr/types/wlr_layer_shell_v1.h b/include/wlr/types/wlr_layer_shell_v1.h
index e97c7311..3ebdbeda 100644
--- a/include/wlr/types/wlr_layer_shell_v1.h
+++ b/include/wlr/types/wlr_layer_shell_v1.h
@@ -140,8 +140,17 @@ uint32_t wlr_layer_surface_v1_configure(struct wlr_layer_surface_v1 *surface,
  */
 void wlr_layer_surface_v1_destroy(struct wlr_layer_surface_v1 *surface);
 
+/**
+ * Returns true if the surface has the layer surface role.
+ */
 bool wlr_surface_is_layer_surface(struct wlr_surface *surface);
 
+/**
+ * Get a struct wlr_layer_surface from a struct wlr_surface.
+ * Asserts that the surface has the layer surface role.
+ * May return NULL even if the surface has the layer surface role if the
+ * corresponding layer surface has been destroyed.
+ */
 struct wlr_layer_surface_v1 *wlr_layer_surface_v1_from_wlr_surface(
 		struct wlr_surface *surface);
 
diff --git a/include/wlr/types/wlr_session_lock_v1.h b/include/wlr/types/wlr_session_lock_v1.h
index 101fe56c..c09978c7 100644
--- a/include/wlr/types/wlr_session_lock_v1.h
+++ b/include/wlr/types/wlr_session_lock_v1.h
@@ -91,7 +91,17 @@ uint32_t wlr_session_lock_surface_v1_configure(
 	struct wlr_session_lock_surface_v1 *lock_surface,
 	uint32_t width, uint32_t height);
 
+/**
+ * Returns true if the surface has the session lock surface role.
+ */
 bool wlr_surface_is_session_lock_surface_v1(struct wlr_surface *surface);
+
+/**
+ * Get a struct wlr_session_lock_surface_v1 from a struct wlr_surface.
+ * Asserts that the surface has the session lock surface role.
+ * May return NULL even if the surface has the session lock surface role if the
+ * corresponding session lock surface has been destroyed.
+ */
 struct wlr_session_lock_surface_v1 *wlr_session_lock_surface_v1_from_wlr_surface(
 	struct wlr_surface *surface);
 
diff --git a/include/wlr/types/wlr_subcompositor.h b/include/wlr/types/wlr_subcompositor.h
index d8e57ed8..e7f6ab2f 100644
--- a/include/wlr/types/wlr_subcompositor.h
+++ b/include/wlr/types/wlr_subcompositor.h
@@ -63,11 +63,16 @@ struct wlr_subcompositor {
 	} events;
 };
 
+/**
+ * Returns true if the surface has the subsurface role.
+ */
 bool wlr_surface_is_subsurface(struct wlr_surface *surface);
 
 /**
- * Get a subsurface from a surface. Can return NULL if the subsurface has been
- * destroyed.
+ * Get a struct wlr_subsurface from a struct wlr_surface.
+ * Asserts that the surface has the subsurface role.
+ * May return NULL even if the surface has the subsurface role if the
+ * corresponding subsurface has been destroyed.
  */
 struct wlr_subsurface *wlr_subsurface_from_wlr_surface(
 	struct wlr_surface *surface);
diff --git a/include/wlr/types/wlr_xdg_shell.h b/include/wlr/types/wlr_xdg_shell.h
index 802f03a5..b4ef2e94 100644
--- a/include/wlr/types/wlr_xdg_shell.h
+++ b/include/wlr/types/wlr_xdg_shell.h
@@ -462,8 +462,17 @@ struct wlr_surface *wlr_xdg_surface_popup_surface_at(
 		struct wlr_xdg_surface *surface, double sx, double sy,
 		double *sub_x, double *sub_y);
 
+/**
+ * Returns true if the surface has the xdg surface role.
+ */
 bool wlr_surface_is_xdg_surface(struct wlr_surface *surface);
 
+/**
+ * Get a struct wlr_xdg_surface from a struct wlr_surface.
+ * Asserts that the surface has the xdg surface role.
+ * May return NULL even if the surface has the xdg surface role if the
+ * corresponding xdg surface has been destroyed.
+ */
 struct wlr_xdg_surface *wlr_xdg_surface_from_wlr_surface(
 		struct wlr_surface *surface);
 
diff --git a/include/wlr/xwayland.h b/include/wlr/xwayland.h
index f1c76f69..ca35da80 100644
--- a/include/wlr/xwayland.h
+++ b/include/wlr/xwayland.h
@@ -273,8 +273,17 @@ void wlr_xwayland_surface_set_fullscreen(struct wlr_xwayland_surface *surface,
 void wlr_xwayland_set_seat(struct wlr_xwayland *xwayland,
 	struct wlr_seat *seat);
 
+/**
+ * Returns true if the surface has the xwayland surface role.
+ */
 bool wlr_surface_is_xwayland_surface(struct wlr_surface *surface);
 
+/**
+ * Get a struct wlr_xwayland_surface from a struct wlr_surface.
+ * Asserts that the surface has the xwayland surface role.
+ * May return NULL even if the surface has the xwayland surface role if the
+ * corresponding xwayland surface has been destroyed.
+ */
 struct wlr_xwayland_surface *wlr_xwayland_surface_from_wlr_surface(
 	struct wlr_surface *surface);