gsk: Document gsk_renderer_realize()

Document the return value and more importantly, specify that a call to
`gsk_renderer_realize()` needs to be matched with a call
`gsk_renderer_unrealize()`.

Prevents issues like https://gitlab.gnome.org/GNOME/gtk/-/issues/4625

1 files changed, 6 insertions, 1 deletions

diff --git a/gsk/gskrenderer.c b/gsk/gskrenderer.c
index ff4ff976ce..b782cfd493 100644
--- a/gsk/gskrenderer.c
+++ b/gsk/gskrenderer.c
@@ -289,10 +289,15 @@ gsk_renderer_is_realized (GskRenderer *renderer)
  *
  * Since GTK 4.6, the surface may be `NULL`, which allows using
  * renderers without having to create a surface.
+ *
+ * Note that it is mandatory to call [method@Gsk.Renderer.unrealize] before
+ * destroying the renderer.
+ *
+ * Returns: Whether the renderer was successfully realized
  */
 gboolean
 gsk_renderer_realize (GskRenderer  *renderer,
-                      GdkSurface    *surface,
+                      GdkSurface   *surface,
                       GError      **error)
 {
   GskRendererPrivate *priv = gsk_renderer_get_instance_private (renderer);