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

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