window/surface-actor: Add docstrings

Redefine the docstring for functions using shaped texture, setting the clip
as nullable.

https://gitlab.gnome.org/GNOME/mutter/merge_requests/79

src/compositor/meta-surface-actor.c

@@ -300,6 +300,21 @@ meta_surface_actor_init (MetaSurfaceActor *self)
                                   CLUTTER_REQUEST_CONTENT_SIZE);
 }
 
+/**
+ * meta_surface_actor_get_image:
+ * @self: A #MetaSurfaceActor
+ * @clip: (nullable): A clipping rectangle. The clip region is in
+ * the same coordinate space as the contents preferred size.
+ * For a shaped texture of a wl_surface, this means surface
+ * coordinate space. If NULL, the whole content will be used.
+ *
+ * Get the image from the texture content. The resulting size of
+ * the returned image may be different from the preferred size of
+ * the shaped texture content.
+ *
+ * Returns: (nullable) (transfer full): a new cairo surface to be freed
+ * with cairo_surface_destroy().
+ */
 cairo_surface_t *
 meta_surface_actor_get_image (MetaSurfaceActor      *self,
                               cairo_rectangle_int_t *clip)

src/compositor/meta-window-actor.c

@@ -2142,6 +2142,19 @@ meta_window_actor_notify_damaged (MetaWindowActor *window_actor)
   g_signal_emit (window_actor, signals[DAMAGED], 0);
 }
 
+/**
+ * meta_window_actor_get_image:
+ * @self: A #MetaWindowActor
+ * @clip: (nullable): A clipping rectangle, to help prevent extra processing.
+ * In the case that the clipping rectangle is partially or fully
+ * outside the bounds of the actor, the rectangle will be clipped.
+ *
+ * Flattens the layers of @self into one ARGB32 image by alpha blending
+ * the images, and returns the flattened image.
+ *
+ * Returns: (nullable) (transfer full): a new cairo surface to be freed with
+ * cairo_surface_destroy().
+ */
 cairo_surface_t *
 meta_window_actor_get_image (MetaWindowActor *self,
                              MetaRectangle   *clip)