[gtk+] Copy in annotations missing from gtkdnd-quartz and gtkclipboard-quartz

[John Ralls <jralls src gnome org>]

commit 398dc1cf27293554ace9de75c43c14d403109c35
Author: John Ralls <jralls ceridwen us>
Date:   Mon Jul 16 15:09:28 2012 -0700

    Copy in annotations missing from gtkdnd-quartz and gtkclipboard-quartz

 gtk/gtkclipboard-quartz.c |  169 ++++++++++++++++++++++++++++++++++++++++++++
 gtk/gtkdnd-quartz.c       |  170 ++++++++++++++++++++++++++++++++++++++-------
 2 files changed, 314 insertions(+), 25 deletions(-)
---
diff --git a/gtk/gtkclipboard-quartz.c b/gtk/gtkclipboard-quartz.c
index a9e2579..3a765d3 100644
--- a/gtk/gtkclipboard-quartz.c
+++ b/gtk/gtkclipboard-quartz.c
@@ -247,6 +247,11 @@ clipboard_display_closed (GdkDisplay   *display,
   g_object_unref (clipboard);
 }
 
+/**
+ * gtk_clipboard_get_for_display:
+ * @display: the display for which the clipboard is to be retrieved or created
+ * @selection: a #GdkAtom which identifies the clipboard to use.
+ */
 GtkClipboard *
 gtk_clipboard_get_for_display (GdkDisplay *display,
 			       GdkAtom     selection)
@@ -257,6 +262,10 @@ gtk_clipboard_get_for_display (GdkDisplay *display,
   return clipboard_peek (display, selection, FALSE);
 }
 
+/**
+ * gtk_clipboard_get:
+ * @selection: a #GdkAtom which identifies the clipboard to use
+ */
 GtkClipboard *
 gtk_clipboard_get (GdkAtom selection)
 {
@@ -380,6 +389,18 @@ gtk_clipboard_set_contents (GtkClipboard         *clipboard,
   return TRUE;
 }
 
+/**
+ * gtk_clipboard_set_with_data: (skip)
+ * @clipboard: a #GtkClipboard
+ * @targets: (array length=n_targets): array containing information
+ *     about the available forms for the clipboard data
+ * @n_targets: number of elements in @targets
+ * @get_func: (scope async): function to call to get the actual clipboard data
+ * @clear_func: (scope async): when the clipboard contents are set again,
+ *     this function will be called, and @get_func will not be subsequently
+ *     called.
+ * @user_data: user data to pass to @get_func and @clear_func.
+ */
 gboolean
 gtk_clipboard_set_with_data (GtkClipboard          *clipboard,
 			     const GtkTargetEntry  *targets,
@@ -397,6 +418,19 @@ gtk_clipboard_set_with_data (GtkClipboard          *clipboard,
 				     FALSE);
 }
 
+/**
+ * gtk_clipboard_set_with_owner: (skip)
+ * @clipboard: a #GtkClipboard
+ * @targets: (array length=n_targets): array containing information
+ *     about the available forms for the clipboard data
+ * @n_targets: number of elements in @targets
+ * @get_func: (scope async): function to call to get the actual clipboard data
+ * @clear_func: (scope async): when the clipboard contents are set again,
+ *     this function will be called, and @get_func will not be subsequently
+ *     called
+ * @owner: an object that "owns" the data. This object will be passed
+ *     to the callbacks when called
+ */
 gboolean
 gtk_clipboard_set_with_owner (GtkClipboard          *clipboard,
 			      const GtkTargetEntry  *targets,
@@ -415,6 +449,10 @@ gtk_clipboard_set_with_owner (GtkClipboard          *clipboard,
 				     TRUE);
 }
 
+/**
+ * gtk_clipboard_get_owner:
+ * @clipboard: a #GtkClipboard
+ */
 GObject *
 gtk_clipboard_get_owner (GtkClipboard *clipboard)
 {
@@ -470,6 +508,10 @@ clipboard_unset (GtkClipboard *clipboard)
     g_object_unref (old_data);
 }
 
+/**
+ * gtk_clipboard_clear:
+ * @clipboard:  a #GtkClipboard
+ */
 void
 gtk_clipboard_clear (GtkClipboard *clipboard)
 {
@@ -492,6 +534,13 @@ text_clear_func (GtkClipboard *clipboard,
   g_free (data);
 }
 
+/**
+ * gtk_clipboard_set_text:
+ * @clipboard: a #GtkClipboard object
+ * @text:      a UTF-8 string.
+ * @len:       length of @text, in bytes, or -1, in which case
+ *             the length will be determined with <function>strlen()</function>.
+ */
 void 
 gtk_clipboard_set_text (GtkClipboard *clipboard,
 			const gchar  *text,
@@ -529,6 +578,11 @@ pixbuf_clear_func (GtkClipboard *clipboard,
   g_object_unref (data);
 }
 
+/**
+ * gtk_clipboard_set_image:
+ * @clipboard: a #GtkClipboard object
+ * @pixbuf:    a #GdkPixbuf 
+ */
 void
 gtk_clipboard_set_image (GtkClipboard *clipboard,
 			 GdkPixbuf    *pixbuf)
@@ -564,6 +618,16 @@ gtk_clipboard_set_image (GtkClipboard *clipboard,
   gtk_target_list_unref (list);
 }
 
+/**
+ * gtk_clipboard_request_contents:
+ * @clipboard: a #GtkClipboard
+ * @target: an atom representing the form into which the clipboard
+ *     owner should convert the selection.
+ * @callback: (scope async): A function to call when the results are received
+ *     (or the retrieval fails). If the retrieval fails the length field of
+ *     @selection_data will be negative.
+ * @user_data: user data to pass to @callback
+ */
 void 
 gtk_clipboard_request_contents (GtkClipboard            *clipboard,
 				GdkAtom                  target,
@@ -579,6 +643,13 @@ gtk_clipboard_request_contents (GtkClipboard            *clipboard,
   gtk_selection_data_free (data);
 }
 
+/**
+ * gtk_clipboard_request_text:
+ * @clipboard: a #GtkClipboard
+ * @callback: (scope async): a function to call when the text is received,
+ *     or the retrieval fails. (It will always be called one way or the other.)
+ * @user_data: user data to pass to @callback.
+ */
 void 
 gtk_clipboard_request_text (GtkClipboard                *clipboard,
 			    GtkClipboardTextReceivedFunc callback,
@@ -591,6 +662,14 @@ gtk_clipboard_request_text (GtkClipboard                *clipboard,
   g_free (data);
 }
 
+/**
+ * gtk_clipboard_request_rich_text:
+ * @clipboard: a #GtkClipboard
+ * @buffer: a #GtkTextBuffer
+ * @callback: (scope async): a function to call when the text is received,
+ *     or the retrieval fails. (It will always be called one way or the other.)
+ * @user_data: user data to pass to @callback.
+ */
 void
 gtk_clipboard_request_rich_text (GtkClipboard                    *clipboard,
                                  GtkTextBuffer                   *buffer,
@@ -611,6 +690,13 @@ gtk_clipboard_wait_for_rich_text (GtkClipboard  *clipboard,
   return NULL;
 }
 
+/**
+ * gtk_clipboard_request_image:
+ * @clipboard: a #GtkClipboard
+ * @callback: (scope async): a function to call when the image is received,
+ *     or the retrieval fails. (It will always be called one way or the other.)
+ * @user_data: user data to pass to @callback.
+ */
 void 
 gtk_clipboard_request_image (GtkClipboard                  *clipboard,
 			     GtkClipboardImageReceivedFunc  callback,
@@ -624,6 +710,13 @@ gtk_clipboard_request_image (GtkClipboard                  *clipboard,
     g_object_unref (pixbuf);
 }
 
+/**
+ * gtk_clipboard_request_uris:
+ * @clipboard: a #GtkClipboard
+ * @callback: (scope async): a function to call when the URIs are received,
+ *     or the retrieval fails. (It will always be called one way or the other.)
+ * @user_data: user data to pass to @callback.
+ */
 void 
 gtk_clipboard_request_uris (GtkClipboard                *clipboard,
 			    GtkClipboardURIReceivedFunc  callback,
@@ -636,6 +729,14 @@ gtk_clipboard_request_uris (GtkClipboard                *clipboard,
   g_strfreev (uris);
 }
 
+/**
+ * gtk_clipboard_request_targets:
+ * @clipboard: a #GtkClipboard
+ * @callback: (scope async): a function to call when the targets are
+ *     received, or the retrieval fails. (It will always be called
+ *     one way or the other.)
+ * @user_data: user data to pass to @callback.
+ */
 void 
 gtk_clipboard_request_targets (GtkClipboard                *clipboard,
 			       GtkClipboardTargetsReceivedFunc callback,
@@ -650,6 +751,12 @@ gtk_clipboard_request_targets (GtkClipboard                *clipboard,
 }
 
 
+/**
+ * gtk_clipboard_wait_for_contents:
+ * @clipboard: a #GtkClipboard
+ * @target: an atom representing the form into which the clipboard
+ *          owner should convert the selection.
+ */
 GtkSelectionData *
 gtk_clipboard_wait_for_contents (GtkClipboard *clipboard,
 				 GdkAtom       target)
@@ -695,6 +802,10 @@ gtk_clipboard_wait_for_contents (GtkClipboard *clipboard,
   return selection_data;
 }
 
+/**
+ * gtk_clipboard_wait_for_text:
+ * @clipboard: a #GtkClipboard
+ */
 gchar *
 gtk_clipboard_wait_for_text (GtkClipboard *clipboard)
 {
@@ -711,6 +822,10 @@ gtk_clipboard_wait_for_text (GtkClipboard *clipboard)
   return result;
 }
 
+/**
+ * gtk_clipboard_wait_for_image:
+ * @clipboard: a #GtkClipboard
+ */
 GdkPixbuf *
 gtk_clipboard_wait_for_image (GtkClipboard *clipboard)
 {
@@ -735,6 +850,10 @@ gtk_clipboard_wait_for_image (GtkClipboard *clipboard)
   return NULL;
 }
 
+/**
+ * gtk_clipboard_wait_for_uris:
+ * @clipboard: a #GtkClipboard
+ */
 gchar **
 gtk_clipboard_wait_for_uris (GtkClipboard *clipboard)
 {
@@ -754,6 +873,10 @@ gtk_clipboard_wait_for_uris (GtkClipboard *clipboard)
   return NULL;
 }
 
+/**
+ * gtk_clipboard_get_display:
+ * @clipboard: a #GtkClipboard
+ */
 GdkDisplay *
 gtk_clipboard_get_display (GtkClipboard *clipboard)
 {
@@ -762,6 +885,10 @@ gtk_clipboard_get_display (GtkClipboard *clipboard)
   return clipboard->display;
 }
 
+/**
+ * gtk_clipboard_wait_is_text_available:
+ * @clipboard: a #GtkClipboard
+ */
 gboolean
 gtk_clipboard_wait_is_text_available (GtkClipboard *clipboard)
 {
@@ -778,6 +905,11 @@ gtk_clipboard_wait_is_text_available (GtkClipboard *clipboard)
   return result;
 }
 
+/**
+ * gtk_clipboard_wait_is_rich_text_available:
+ * @clipboard: a #GtkClipboard
+ * @buffer: a #GtkTextBuffer
+ */
 gboolean
 gtk_clipboard_wait_is_rich_text_available (GtkClipboard  *clipboard,
                                            GtkTextBuffer *buffer)
@@ -798,6 +930,10 @@ gtk_clipboard_wait_is_rich_text_available (GtkClipboard  *clipboard,
   return result;
 }
 
+/**
+ * gtk_clipboard_wait_is_image_available:
+ * @clipboard: a #GtkClipboard
+ */
 gboolean
 gtk_clipboard_wait_is_image_available (GtkClipboard *clipboard)
 {
@@ -815,6 +951,10 @@ gtk_clipboard_wait_is_image_available (GtkClipboard *clipboard)
   return result;
 }
 
+/**
+ * gtk_clipboard_wait_is_uris_available:
+ * @clipboard: a #GtkClipboard
+ */
 gboolean
 gtk_clipboard_wait_is_uris_available (GtkClipboard *clipboard)
 {
@@ -832,6 +972,14 @@ gtk_clipboard_wait_is_uris_available (GtkClipboard *clipboard)
   return result;
 }
 
+/**
+ * gtk_clipboard_wait_for_targets:
+ * @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: location to store number of items in @targets.
+ */
 gboolean
 gtk_clipboard_wait_for_targets (GtkClipboard  *clipboard, 
 				GdkAtom      **targets,
@@ -962,6 +1110,11 @@ gtk_clipboard_owner_change (GtkClipboard        *clipboard,
     }
 }
 
+/**
+ * gtk_clipboard_wait_is_target_available:
+ * @clipboard: a #GtkClipboard
+ * @target:    A #GdkAtom indicating which target to look for.
+ */
 gboolean
 gtk_clipboard_wait_is_target_available (GtkClipboard *clipboard,
 					GdkAtom       target)
@@ -987,11 +1140,23 @@ gtk_clipboard_wait_is_target_available (GtkClipboard *clipboard,
   return retval;
 }
 
+/**
+ * _gtk_clipboard_handle_event:
+ * @event: a owner change event
+ */
 void 
 _gtk_clipboard_handle_event (GdkEventOwnerChange *event)
 {
 }
 
+/**
+ * gtk_clipboard_set_can_store:
+ * @clipboard: a #GtkClipboard
+ * @targets: (allow-none) (array length=n_targets): array containing
+ *           information about which forms should be stored or %NULL
+ *           to indicate that all forms should be stored.
+ * @n_targets: number of elements in @targets
+ */
 void
 gtk_clipboard_set_can_store (GtkClipboard         *clipboard,
  			     const GtkTargetEntry *targets,
@@ -1000,6 +1165,10 @@ gtk_clipboard_set_can_store (GtkClipboard         *clipboard,
   /* FIXME: Implement */
 }
 
+/**
+ * gtk_clipboard_store:
+ * @clipboard: a #GtkClipboard
+ */
 void
 gtk_clipboard_store (GtkClipboard *clipboard)
 {
diff --git a/gtk/gtkdnd-quartz.c b/gtk/gtkdnd-quartz.c
index cf8a1b5..9f13e5f 100644
--- a/gtk/gtkdnd-quartz.c
+++ b/gtk/gtkdnd-quartz.c
@@ -177,6 +177,16 @@ struct _GtkDragFindData
 
 @end
 
+/**
+ * gtk_drag_get_data: (method)
+ * @widget: the widget that will receive the
+ *   #GtkWidget::drag-data-received signal.
+ * @context: the drag context
+ * @target: the target (form of the data) to retrieve.
+ * @time_: a timestamp for retrieving the data. This will
+ *   generally be the time received in a #GtkWidget::drag-motion"
+ *   or #GtkWidget::drag-drop" signal.
+ */
 void 
 gtk_drag_get_data (GtkWidget      *widget,
 		   GdkDragContext *context,
@@ -233,6 +243,14 @@ gtk_drag_get_data (GtkWidget      *widget,
     }      
 }
 
+/**
+ * gtk_drag_finish: (method)
+ * @context: the drag context.
+ * @success: a flag indicating whether the drop was successful
+ * @del: a flag indicating whether the source should delete the
+ *   original data. (This should be %TRUE for a move)
+ * @time_: the timestamp from the #GtkWidget::drag-drop signal.
+ */
 void 
 gtk_drag_finish (GdkDragContext *context,
 		 gboolean        success,
@@ -312,6 +330,10 @@ gtk_drag_clear_source_info (GdkDragContext *context)
   g_object_set_qdata (G_OBJECT (context), dest_info_quark, NULL);
 }
 
+/**
+ * gtk_drag_get_source_widget: (method)
+ * @context: a (destination side) drag context
+ */
 GtkWidget *
 gtk_drag_get_source_widget (GdkDragContext *context)
 {
@@ -364,14 +386,10 @@ gtk_drag_highlight_draw (GtkWidget *widget,
   return FALSE;
 }
 
-/*************************************************************
- * gtk_drag_highlight:
- *     Highlight the given widget in the default manner.
- *   arguments:
- *     widget:
- *   results:
- *************************************************************/
-
+/**
+ * gtk_drag_highlight: (method)
+ * @widget: a widget to highlight
+ */
 void 
 gtk_drag_highlight (GtkWidget  *widget)
 {
@@ -384,14 +402,10 @@ gtk_drag_highlight (GtkWidget  *widget)
   gtk_widget_queue_draw (widget);
 }
 
-/*************************************************************
- * gtk_drag_unhighlight:
- *     Refresh the given widget to remove the highlight.
- *   arguments:
- *     widget:
- *   results:
- *************************************************************/
-
+/**
+ * gtk_drag_unhighlight: (method)
+ * @widget: a widget to remove the highlight from.
+ */
 void 
 gtk_drag_unhighlight (GtkWidget *widget)
 {
@@ -468,6 +482,17 @@ gtk_drag_dest_site_destroy (gpointer data)
   g_free (site);
 }
 
+/**
+ * gtk_drag_dest_set: (method)
+ * @widget: a #GtkWidget
+ * @flags: which types of default drag behavior to use
+ * @targets: (allow-none) (array length=n_targets): a pointer to an array of #GtkTargetEntry<!-- -->s
+ *     indicating the drop types that this @widget will accept, or %NULL.
+ *     Later you can access the list with gtk_drag_dest_get_target_list()
+ *     and gtk_drag_dest_find_target().
+ * @n_targets: the number of entries in @targets
+ * @actions: a bitmask of possible actions for a drop onto this @widget.
+ */
 void 
 gtk_drag_dest_set (GtkWidget            *widget,
 		   GtkDestDefaults       flags,
@@ -509,6 +534,16 @@ gtk_drag_dest_set (GtkWidget            *widget,
 			  site, gtk_drag_dest_site_destroy);
 }
 
+/**
+ * gtk_drag_dest_set_proxy: (method)
+ * @widget: a #GtkWidget
+ * @proxy_window: the window to which to forward drag events
+ * @protocol: the drag protocol which the @proxy_window accepts
+ *   (You can use gdk_drag_get_protocol() to determine this)
+ * @use_coordinates: If %TRUE, send the same coordinates to the
+ *   destination, because it is an embedded
+ *   subwindow.
+ */
 void 
 gtk_drag_dest_set_proxy (GtkWidget      *widget,
 			 GdkWindow      *proxy_window,
@@ -518,6 +553,10 @@ gtk_drag_dest_set_proxy (GtkWidget      *widget,
   g_warning ("gtk_drag_dest_set_proxy is not supported on Mac OS X.");
 }
 
+/**
+ * gtk_drag_dest_unset: (method)
+ * @widget: a #GtkWidget
+ */
 void 
 gtk_drag_dest_unset (GtkWidget *widget)
 {
@@ -539,6 +578,10 @@ gtk_drag_dest_unset (GtkWidget *widget)
   g_object_set_data (G_OBJECT (widget), I_("gtk-drag-dest"), NULL);
 }
 
+/**
+ * gtk_drag_dest_get_target_list: (method)
+ * @widget: a #GtkWidget
+ */
 GtkTargetList*
 gtk_drag_dest_get_target_list (GtkWidget *widget)
 {
@@ -551,6 +594,11 @@ gtk_drag_dest_get_target_list (GtkWidget *widget)
   return site ? site->target_list : NULL;  
 }
 
+/**
+ * gtk_drag_dest_set_target_list: (method)
+ * @widget: a #GtkWidget that's a drag destination
+ * @target_list: (allow-none): list of droppable targets, or %NULL for none
+ */
 void
 gtk_drag_dest_set_target_list (GtkWidget      *widget,
                                GtkTargetList  *target_list)
@@ -579,6 +627,10 @@ gtk_drag_dest_set_target_list (GtkWidget      *widget,
   register_types (widget, site);
 }
 
+/**
+ * gtk_drag_dest_add_text_targets: (method)
+ * @widget: a #GtkWidget that's a drag destination
+ */
 void
 gtk_drag_dest_add_text_targets (GtkWidget *widget)
 {
@@ -594,6 +646,11 @@ gtk_drag_dest_add_text_targets (GtkWidget *widget)
   gtk_target_list_unref (target_list);
 }
 
+
+/**
+ * gtk_drag_dest_add_image_targets: (method)
+ * @widget: a #GtkWidget that's a drag destination
+ */
 void
 gtk_drag_dest_add_image_targets (GtkWidget *widget)
 {
@@ -609,6 +666,10 @@ gtk_drag_dest_add_image_targets (GtkWidget *widget)
   gtk_target_list_unref (target_list);
 }
 
+/**
+ * gtk_drag_dest_add_uri_targets: (method)
+ * @widget: a #GtkWidget that's a drag destination
+ */
 void
 gtk_drag_dest_add_uri_targets (GtkWidget *widget)
 {
@@ -876,6 +937,11 @@ gtk_drag_dest_drop (GtkWidget	     *widget,
   return (site->flags & GTK_DEST_DEFAULT_DROP) ? TRUE : retval;
 }
 
+/**
+ * gtk_drag_dest_set_track_motion: (method)
+ * @widget: a #GtkWidget that's a drag destination
+ * @track_motion: whether to accept all targets
+ */
 void
 gtk_drag_dest_set_track_motion (GtkWidget *widget,
 				gboolean   track_motion)
@@ -891,6 +957,10 @@ gtk_drag_dest_set_track_motion (GtkWidget *widget,
   site->track_motion = track_motion != FALSE;
 }
 
+/**
+ * gtk_drag_dest_get_track_motion: (method)
+ * @widget: a #GtkWidget that's a drag destination
+ */
 gboolean
 gtk_drag_dest_get_track_motion (GtkWidget *widget)
 {
@@ -989,6 +1059,13 @@ _gtk_drag_dest_handle_event (GtkWidget *toplevel,
 }
 
 
+/**
+ * gtk_drag_dest_find_target: (method)
+ * @widget: drag destination widget
+ * @context: drag context
+ * @target_list: (allow-none): list of droppable targets, or %NULL to use
+ *    gtk_drag_dest_get_target_list (@widget).
+ */
 GdkAtom
 gtk_drag_dest_find_target (GtkWidget      *widget,
                            GdkDragContext *context,
@@ -1231,6 +1308,15 @@ gtk_drag_begin_internal (GtkWidget         *widget,
   return context;
 }
 
+/**
+ * gtk_drag_begin: (method)
+ * @widget: the source widget.
+ * @targets: The targets (data formats) in which the
+ *    source can provide the data.
+ * @actions: A bitmask of the allowed drag actions for this drag.
+ * @button: The button the user clicked to start the drag.
+ * @event: The event that triggered the start of the drag.
+ */
 GdkDragContext *
 gtk_drag_begin (GtkWidget         *widget,
 		GtkTargetList     *targets,
@@ -1306,6 +1392,15 @@ gtk_drag_source_event_cb (GtkWidget      *widget,
   return retval;
 }
 
+/**
+ * gtk_drag_source_set: (method)
+ * @widget: a #GtkWidget
+ * @start_button_mask: the bitmask of buttons that can start the drag
+ * @targets: (allow-none) (array length=n_targets): the table of targets that the drag will support,
+ *     may be %NULL
+ * @n_targets: the number of items in @targets
+ * @actions: the bitmask of possible actions for a drag from this widget
+ */
 void 
 gtk_drag_source_set (GtkWidget            *widget,
 		     GdkModifierType       start_button_mask,
@@ -1357,14 +1452,10 @@ gtk_drag_source_set (GtkWidget            *widget,
   site->actions = actions;
 }
 
-/*************************************************************
- * gtk_drag_source_unset
- *     Unregister this widget as a drag source.
- *   arguments:
- *     widget:
- *   results:
- *************************************************************/
-
+/**
+ * gtk_drag_source_unset: (method)
+ * @widget: a #GtkWidget
+ */
 void 
 gtk_drag_source_unset (GtkWidget *widget)
 {
@@ -1383,6 +1474,10 @@ gtk_drag_source_unset (GtkWidget *widget)
     }
 }
 
+/**
+ * gtk_drag_source_get_target_list: (method)
+ * @widget: a #GtkWidget
+ */
 GtkTargetList *
 gtk_drag_source_get_target_list (GtkWidget *widget)
 {
@@ -1396,6 +1491,11 @@ gtk_drag_source_get_target_list (GtkWidget *widget)
 
 }
 
+/**
+ * gtk_drag_source_set_target_list: (method)
+ * @widget: a #GtkWidget that's a drag source
+ * @target_list: (allow-none): list of draggable targets, or %NULL for none
+ */
 void
 gtk_drag_source_set_target_list (GtkWidget     *widget,
                                  GtkTargetList *target_list)
@@ -1448,6 +1548,10 @@ gtk_drag_source_add_text_targets (GtkWidget *widget)
   gtk_target_list_unref (target_list);
 }
 
+/**
+ * gtk_drag_source_add_image_targets: (method)
+ * @widget: a #GtkWidget that's is a drag source
+ */
 void
 gtk_drag_source_add_image_targets (GtkWidget *widget)
 {
@@ -1463,6 +1567,10 @@ gtk_drag_source_add_image_targets (GtkWidget *widget)
   gtk_target_list_unref (target_list);
 }
 
+/**
+ * gtk_drag_source_add_uri_targets: (method)
+ * @widget: a #GtkWidget that's is a drag source
+ */
 void
 gtk_drag_source_add_uri_targets (GtkWidget *widget)
 {
@@ -1513,6 +1621,11 @@ gtk_drag_source_site_destroy (gpointer data)
   g_free (site);
 }
 
+/**
+ * gtk_drag_source_set_icon_pixbuf: (method)
+ * @widget: a #GtkWidget
+ * @pixbuf: the #GdkPixbuf for the drag icon
+ */
 void 
 gtk_drag_source_set_icon_pixbuf (GtkWidget   *widget,
 				 GdkPixbuf   *pixbuf)
@@ -1925,7 +2038,14 @@ _gtk_drag_source_handle_event (GtkWidget *widget,
     }  
 }
 
-
+/**
+ * gtk_drag_check_threshold: (method)
+ * @widget: a #GtkWidget
+ * @start_x: X coordinate of start of drag
+ * @start_y: Y coordinate of start of drag
+ * @current_x: current X coordinate
+ * @current_y: current Y coordinate
+ */
 gboolean
 gtk_drag_check_threshold (GtkWidget *widget,
 			  gint       start_x,