[mutter] window/surface-actor: Add docstrings

[Jonas Ådahl <jadahl src gnome org>]

commit b8a49a682e5e8d9c79027f9c54ac695bb5098ce5
Author: Marco Trevisan (Treviño) <mail 3v1n0 net>
Date:   Fri Sep 13 06:01:54 2019 +0200

    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 | 15 +++++++++++++++
 src/compositor/meta-window-actor.c  | 13 +++++++++++++
 2 files changed, 28 insertions(+)
---
diff --git a/src/compositor/meta-surface-actor.c b/src/compositor/meta-surface-actor.c
index 26915115f..c910a145b 100644
--- a/src/compositor/meta-surface-actor.c
+++ b/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)
diff --git a/src/compositor/meta-window-actor.c b/src/compositor/meta-window-actor.c
index 53f46db7b..a80407ae7 100644
--- a/src/compositor/meta-window-actor.c
+++ b/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)