[gtk/gtk-3-24: 1/2] gtkclipboard-quartz: Update annotations for gtk_clipboard_wait_for_targets

[Matthias Clasen <matthiasc src gnome org>]

commit 593025a917b8d7b881952743aecf17cfbbc79e2f
Author: Tomasz Miąsko <tomasz miasko gmail com>
Date:   Sun Mar 10 00:00:00 2019 +0000

    gtkclipboard-quartz: Update annotations for gtk_clipboard_wait_for_targets
    
    Copy documentation for gtk_clipboard_wait_for_targets from gtk/gtkclipboard.c
    to quartz implementation. Primarily to add transfer container annotation as
    otherwise pygobject tries to deallocate individual GdkAtoms.
    
    Issue #1584.

 gtk/gtkclipboard-quartz.c | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)
---
diff --git a/gtk/gtkclipboard-quartz.c b/gtk/gtkclipboard-quartz.c
index 4838bb16c5..75699cccf5 100644
--- a/gtk/gtkclipboard-quartz.c
+++ b/gtk/gtkclipboard-quartz.c
@@ -1006,9 +1006,22 @@ gtk_clipboard_wait_is_uris_available (GtkClipboard *clipboard)
 
 /**
  * gtk_clipboard_wait_for_targets:
- * @clipboard:
- * @targets: (out) (array length=n_targets):
- * @n_targets: (out):
+ * @clipboard: a #GtkClipboard
+ * @targets: (out) (array length=n_targets) (transfer container): location
+ *           to store an array of targets. The result stored here must
+ *           be freed with g_free().
+ * @n_targets: (out): location to store number of items in @targets.
+ *
+ * Returns a list of targets that are present on the clipboard, or %NULL
+ * if there aren’t any targets available. The returned list must be
+ * freed with g_free().
+ * This function waits for the data to be received using the main
+ * loop, so events, timeouts, etc, may be dispatched during the wait.
+ *
+ * Returns: %TRUE if any targets are present on the clipboard,
+ *               otherwise %FALSE.
+ *
+ * Since: 2.4
  */
 gboolean
 gtk_clipboard_wait_for_targets (GtkClipboard  *clipboard,