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.

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);
 

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);
 

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);
 

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
+ * Get a struct wlr_subsurface from a struct wlr_surface.
- * destroyed.
+ * 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);

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);
 

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);