[gtk+] Document new clipboard apis

[Matthias Clasen <matthiasc src gnome org>]

commit b775238bc4326a6f122aaaf93d93e4b370134f8b
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Oct 23 05:53:23 2017 +0200

    Document new clipboard apis
    
    These are surface-based replacements for some pixbuf apis.

 docs/reference/gtk/gtk4-sections.txt |    2 ++
 gtk/gtkclipboard.c                   |   30 ++++++++++++++++++++++++++++++
 2 files changed, 32 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt
index 38591fc..8edf9fb 100644
--- a/docs/reference/gtk/gtk4-sections.txt
+++ b/docs/reference/gtk/gtk4-sections.txt
@@ -5302,6 +5302,7 @@ gtk_clipboard_get_owner
 gtk_clipboard_clear
 gtk_clipboard_set_text
 gtk_clipboard_set_image
+gtk_clipboard_set_surface
 gtk_clipboard_request_contents
 gtk_clipboard_request_text
 gtk_clipboard_request_image
@@ -5311,6 +5312,7 @@ gtk_clipboard_request_uris
 gtk_clipboard_wait_for_contents
 gtk_clipboard_wait_for_text
 gtk_clipboard_wait_for_image
+gtk_clipboard_wait_for_surface
 gtk_clipboard_wait_for_rich_text
 gtk_clipboard_wait_for_uris
 gtk_clipboard_wait_is_text_available
diff --git a/gtk/gtkclipboard.c b/gtk/gtkclipboard.c
index 496e44c..72bc0de 100644
--- a/gtk/gtkclipboard.c
+++ b/gtk/gtkclipboard.c
@@ -930,6 +930,17 @@ gtk_clipboard_set_image (GtkClipboard *clipboard,
   gtk_target_list_unref (list);
 }
 
+/**
+ * gtk_clipboard_set_surface:
+ * @clipboard: a #GtkClipboard object
+ * @surface: a cairo image surface
+ *
+ * Sets the contents of the clipboard to the given cairo image surface.
+ * GTK+ will take responsibility for responding for requests for the
+ * image, and for converting the image into the requested format.
+ * 
+ * Since: 3.94
+ **/
 void
 gtk_clipboard_set_surface (GtkClipboard    *clipboard,
                            cairo_surface_t *surface)
@@ -1651,6 +1662,24 @@ gtk_clipboard_wait_for_image (GtkClipboard *clipboard)
   return results.data;
 }
 
+/**
+ * gtk_clipboard_wait_for_surface:
+ * @clipboard: a #GtkClipboard
+ *
+ * Requests the contents of the clipboard as image and converts
+ * the result to a cairo surface. This function waits for
+ * the data to be received using the main loop, so events,
+ * timeouts, etc, may be dispatched during the wait.
+ *
+ * Returns: (nullable) (transfer full): a newly-allocated cairo surface
+ *     object which must be disposed with cairo_surface_destroy(), or
+ *     %NULL if retrieving the selection data failed. (This could
+ *     happen for various reasons, in particular if the clipboard
+ *     was empty or if the contents of the clipboard could not be
+ *     converted into an image.)
+ *
+ * Since: 2.6
+ **/
 cairo_surface_t *
 gtk_clipboard_wait_for_surface (GtkClipboard *clipboard)
 {
@@ -1676,6 +1705,7 @@ gtk_clipboard_wait_for_surface (GtkClipboard *clipboard)
 
   return results.data;
 }
+
 static void 
 clipboard_uris_received_func (GtkClipboard *clipboard,
                              gchar       **uris,