dragsource: Convert docs

1 files changed, 86 insertions, 86 deletions

diff --git a/gtk/gtkdragsource.c b/gtk/gtkdragsource.c
index b6673c0564..02d76f218e 100644
--- a/gtk/gtkdragsource.c
+++ b/gtk/gtkdragsource.c
@@ -42,22 +42,19 @@
 #include "gtkgesturesingle.h"
 
 /**
- * SECTION:gtkdragsource
- * @Short_description: Event controller to initiate DND operations
- * @Title: GtkDragSource
+ * GtkDragSource:
  *
- * GtkDragSource is an event controller that is used to initiate
- * Drag-And-Drop operations.
+ * `GtkDragSource` is an event controller to initiate Drag-And-Drop operations.
  *
- * GtkDragSource can be set up with the necessary
+ * `GtkDragSource` can be set up with the necessary
  * ingredients for a DND operation ahead of time. This includes
  * the source for the data that is being transferred, in the form
- * of a #GdkContentProvider, the desired action, and the icon to
+ * of a `GdkContentProvider`, the desired action, and the icon to
  * use during the drag operation. After setting it up, the drag
  * source must be added to a widget as an event controller, using
- * gtk_widget_add_controller().
+ * [method@Gtk.Widget.add_controller].
  *
- * |[<!-- language="C" -->
+ * ```c
  * static void
  * my_widget_init (MyWidget *self)
  * {
@@ -68,18 +65,19 @@
  *
  *   gtk_widget_add_controller (GTK_WIDGET (self), GTK_EVENT_CONTROLLER (drag_source));
  * }
- * ]|
+ * ```
  *
- * Setting up the content provider and icon ahead of time only
- * makes sense when the data does not change. More commonly, you
- * will want to set them up just in time. To do so, #GtkDragSource
- * has #GtkDragSource::prepare and #GtkDragSource::drag-begin signals.
+ * Setting up the content provider and icon ahead of time only makes
+ * sense when the data does not change. More commonly, you will want
+ * to set them up just in time. To do so, `GtkDragSource` has
+ * [signal@Gtk.DragSource::prepare] and [signal@Gtk.DragSource::drag-begin]
+ * signals.
  *
  * The ::prepare signal is emitted before a drag is started, and
  * can be used to set the content provider and actions that the
  * drag should be started with.
  *
- * |[<!-- language="C" -->
+ * ```c
  * static GdkContentProvider *
  * on_drag_prepare (GtkDragSource *source,
  *                  double         x,
@@ -97,12 +95,12 @@
  *       gdk_content_provider_new_typed (GDK_TYPE_PIXBUF, pixbuf),
  *     }, 2);
  * }
- * ]|
+ * ```
  *
- * The ::drag-begin signal is emitted after the #GdkDrag object has
+ * The ::drag-begin signal is emitted after the `GdkDrag` object has
  * been created, and can be used to set up the drag icon.
  *
- * |[<!-- language="C" -->
+ * ```c
  * static void
  * on_drag_begin (GtkDragSource *source,
  *                GtkDrag       *drag,
@@ -113,14 +111,14 @@
  *   gtk_drag_source_set_icon (source, paintable, 0, 0);
  *   g_object_unref (paintable);
  * }
- * ]|
+ * ```
  *
- * During the DND operation, GtkDragSource emits signals that
+ * During the DND operation, `GtkDragSource` emits signals that
  * can be used to obtain updates about the status of the operation,
  * but it is not normally necessary to connect to any signals,
  * except for one case: when the supported actions include
  * %GDK_ACTION_MOVE, you need to listen for the
- * #GtkDragSource::drag-end signal and delete the
+ * [signal@Gtk.DragSource::drag-end] signal and delete the
  * data after it has been transferred.
  */
 
@@ -320,11 +318,10 @@ gtk_drag_source_class_init (GtkDragSourceClass *class)
   class->prepare = gtk_drag_source_prepare;
 
   /**
-   * GtkDragSource:content:
+   * GtkDragSource:content: (attributes org.gtk.Property.get=gtk_drag_source_get_content org.gtk.Propery.set=gtk_drag_source_set_content)
    *
-   * The data that is offered by drag operations from this source,
-   * in the form of a #GdkContentProvider.
-   */ 
+   * The data that is offered by drag operations from this source.
+   */
   properties[PROP_CONTENT] =
        g_param_spec_object ("content",
                             P_("Content"),
@@ -333,13 +330,13 @@ gtk_drag_source_class_init (GtkDragSourceClass *class)
                            G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS | G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkDragSource:actions:
+   * GtkDragSource:actions: (attributes org.gtk.Property.get=gtk_drag_source_get_actions org.gtk.Property.set=gtk_drag_source_set_actions)
    *
    * The actions that are supported by drag operations from the source.
    *
-   * Note that you must handle the #GtkDragSource::drag-end signal
+   * Note that you must handle the [signal@Gtk.DragSource::drag-end] signal
    * if the actions include %GDK_ACTION_MOVE.
-   */ 
+   */
   properties[PROP_ACTIONS] =
        g_param_spec_flags ("actions",
                            P_("Actions"),
@@ -351,17 +348,18 @@ gtk_drag_source_class_init (GtkDragSourceClass *class)
 
   /**
    * GtkDragSource::prepare:
-   * @source: the #GtkDragSource
+   * @source: the `GtkDragSource`
    * @x: the X coordinate of the drag starting point
    * @y: the Y coordinate fo the drag starting point
    *
-   * The ::prepare signal is emitted when a drag is about to be initiated.
-   * It returns the * #GdkContentProvider to use for the drag that is about
+   * Emitted when a drag is about to be initiated.
+   *
+   * It returns the `GdkContentProvider` to use for the drag that is about
    * to start. The default handler for this signal returns the value of
-   * the #GtkDragSource:content property, so if you set up that property
-   * ahead of time, you don't need to connect to this signal.
+   * the [property@Gtk.DragSource:content] property, so if you set up that
+   * property ahead of time, you don't need to connect to this signal.
    *
-   * Returns: (transfer full) (nullable): a #GdkContentProvider, or %NULL
+   * Returns: (transfer full) (nullable): a `GdkContentProvider`, or %NULL
    */
   signals[PREPARE] =
       g_signal_new (I_("prepare"),
@@ -375,12 +373,13 @@ gtk_drag_source_class_init (GtkDragSourceClass *class)
 
   /**
    * GtkDragSource::drag-begin:
-   * @source: the #GtkDragSource
-   * @drag: the #GdkDrag object
+   * @source: the `GtkDragSource`
+   * @drag: the `GdkDrag` object
+   *
+   * Emitted on the drag source when a drag is started.
    *
-   * The ::drag-begin signal is emitted on the drag source when a drag
-   * is started. It can be used to e.g. set a custom drag icon with
-   * gtk_drag_source_set_icon().
+   * It can be used to e.g. set a custom drag icon with
+   * [method@Gtk.DragSource.set_icon].
    */
   signals[DRAG_BEGIN] =
       g_signal_new (I_("drag-begin"),
@@ -394,15 +393,17 @@ gtk_drag_source_class_init (GtkDragSourceClass *class)
 
   /**
    * GtkDragSource::drag-end:
-   * @source: the #GtkDragSource
-   * @drag: the #GdkDrag object
+   * @source: the `GtkDragSource`
+   * @drag: the `GdkDrag` object
    * @delete_data: %TRUE if the drag was performing %GDK_ACTION_MOVE,
    *    and the data should be deleted
    *
-   * The ::drag-end signal is emitted on the drag source when a drag is
-   * finished. A typical reason to connect to this signal is to undo
-   * things done in #GtkDragSource::prepare or #GtkDragSource::drag-begin.
-   */ 
+   * Emitted on the drag source when a drag is finished.
+   *
+   * A typical reason to connect to this signal is to undo
+   * things done in [signal@Gtk.DragSource::prepare] or
+   * [signal@Gtk.DragSource::drag-begin] handlers.
+   */
   signals[DRAG_END] =
       g_signal_new (I_("drag-end"),
                     G_TYPE_FROM_CLASS (class),
@@ -416,12 +417,13 @@ gtk_drag_source_class_init (GtkDragSourceClass *class)
 
   /**
    * GtkDragSource::drag-cancel:
-   * @source: the #GtkDragSource
-   * @drag: the #GdkDrag object
+   * @source: the `GtkDragSource`
+   * @drag: the `GdkDrag` object
    * @reason: information on why the drag failed
    *
-   * The ::drag-cancel signal is emitted on the drag source when a drag has
-   * failed. The signal handler may handle a failed drag operation based on
+   * Emitted on the drag source when a drag has failed.
+   *
+   * The signal handler may handle a failed drag operation based on
    * the type of error. It should return %TRUE if the failure has been handled
    * and the default "drag operation failed" animation should not be shown.
    *
@@ -600,9 +602,9 @@ gtk_drag_source_drag_begin (GtkDragSource *source)
 /**
  * gtk_drag_source_new:
  *
- * Creates a new #GtkDragSource object.
+ * Creates a new `GtkDragSource` object.
  *
- * Returns: the new #GtkDragSource
+ * Returns: the new `GtkDragSource`
  */
 GtkDragSource *
 gtk_drag_source_new (void)
@@ -611,12 +613,12 @@ gtk_drag_source_new (void)
 }
 
 /**
- * gtk_drag_source_get_content:
- * @source: a #GtkDragSource
+ * gtk_drag_source_get_content: (attributes org.gtk.Method.get_property=content)
+ * @source: a `GtkDragSource`
  *
- * Gets the current content provider of a #GtkDragSource.
+ * Gets the current content provider of a `GtkDragSource`.
  *
- * Returns: (nullable) (transfer none): the #GdkContentProvider of @source
+ * Returns: (nullable) (transfer none): the `GdkContentProvider` of @source
  */
 GdkContentProvider *
 gtk_drag_source_get_content (GtkDragSource *source)
@@ -627,21 +629,20 @@ gtk_drag_source_get_content (GtkDragSource *source)
 }
 
 /**
- * gtk_drag_source_set_content:
- * @source: a #GtkDragSource
- * @content: (nullable): a #GdkContentProvider, or %NULL
+ * gtk_drag_source_set_content: (attributes org.gtk.Method.set_property=content)
+ * @source: a `GtkDragSource`
+ * @content: (nullable): a `GdkContentProvider`, or %NULL
  *
- * Sets a content provider on a #GtkDragSource.
+ * Sets a content provider on a `GtkDragSource`.
  *
- * When the data is requested in the cause of a
- * DND operation, it will be obtained from the
- * content provider.
+ * When the data is requested in the cause of a DND operation,
+ * it will be obtained from the content provider.
  *
  * This function can be called before a drag is started,
- * or in a handler for the #GtkDragSource::prepare signal.
+ * or in a handler for the [signal@Gtk.DragSource::prepare] signal.
  *
  * You may consider setting the content provider back to
- * %NULL in a #GtkDragSource::drag-end signal handler.
+ * %NULL in a [signal@Gtk.DragSource::drag-end] signal handler.
  */
 void
 gtk_drag_source_set_content (GtkDragSource      *source,
@@ -656,10 +657,10 @@ gtk_drag_source_set_content (GtkDragSource      *source,
 }
 
 /**
- * gtk_drag_source_get_actions:
- * @source: a #GtkDragSource
+ * gtk_drag_source_get_actions: (attributes org.gtk.Method.get_property=actions)
+ * @source: a `GtkDragSource`
  *
- * Gets the actions that are currently set on the #GtkDragSource.
+ * Gets the actions that are currently set on the `GtkDragSource`.
  *
  * Returns: the actions set on @source
  */
@@ -672,20 +673,19 @@ gtk_drag_source_get_actions (GtkDragSource *source)
 }
 
 /**
- * gtk_drag_source_set_actions:
- * @source: a #GtkDragSource
+ * gtk_drag_source_set_actions: (attributes org.gtk.Method.set_property=actions)
+ * @source: a `GtkDragSource`
  * @actions: the actions to offer
  *
- * Sets the actions on the #GtkDragSource.
+ * Sets the actions on the `GtkDragSource`.
  *
- * During a DND operation, the actions are offered
- * to potential drop targets. If @actions include
- * %GDK_ACTION_MOVE, you need to listen to the
- * #GtkDragSource::drag-end signal and handle
- * @delete_data being %TRUE.
+ * During a DND operation, the actions are offered to potential
+ * drop targets. If @actions include %GDK_ACTION_MOVE, you need
+ * to listen to the [signal@Gtk.DragSource::drag-end] signal and
+ * handle @delete_data being %TRUE.
  *
  * This function can be called before a drag is started,
- * or in a handler for the #GtkDragSource::prepare signal.
+ * or in a handler for the [signal@Gtk.DragSource::prepare] signal.
  */
 void
 gtk_drag_source_set_actions (GtkDragSource *source,
@@ -703,7 +703,7 @@ gtk_drag_source_set_actions (GtkDragSource *source,
 
 /**
  * gtk_drag_source_set_icon:
- * @source: a #GtkDragSource
+ * @source: a `GtkDragSource`
  * @paintable: (nullable): the #GdkPaintable to use as icon, or %NULL
  * @hot_x: the hotspot X coordinate on the icon
  * @hot_y: the hotspot Y coordinate on the icon
@@ -716,7 +716,8 @@ gtk_drag_source_set_actions (GtkDragSource *source,
  * If @paintable is %NULL, a default icon is used.
  *
  * This function can be called before a drag is started, or in
- * a #GtkDragSource::prepare or #GtkDragSource::drag-begin signal handler.
+ * a [signal@Gtk.DragSource::prepare] or
+ * [signal@Gtk.DragSource::drag-begin] signal handler.
  */
 void
 gtk_drag_source_set_icon (GtkDragSource *source,
@@ -734,11 +735,12 @@ gtk_drag_source_set_icon (GtkDragSource *source,
 
 /**
  * gtk_drag_source_get_drag:
- * @source: a #GtkDragSource
+ * @source: a `GtkDragSource`
  *
- * Returns the underlying #GdkDrag object for an ongoing drag.
+ * Returns the underlying `GdkDrag` object for an ongoing drag.
  *
- * Returns: (nullable) (transfer none): the #GdkDrag of the current drag operation, or %NULL
+ * Returns: (nullable) (transfer none): the `GdkDrag` of the current
+ *   drag operation, or %NULL
  */
 GdkDrag *
 gtk_drag_source_get_drag (GtkDragSource *source)
@@ -750,7 +752,7 @@ gtk_drag_source_get_drag (GtkDragSource *source)
 
 /**
  * gtk_drag_source_drag_cancel:
- * @source: a #GtkDragSource
+ * @source: a `GtkDragSource`
  *
  * Cancels a currently ongoing drag operation.
  */
@@ -775,10 +777,8 @@ gtk_drag_source_drag_cancel (GtkDragSource *source)
  * @start_y: Y coordinate of start of drag
  * @current_x: current X coordinate
  * @current_y: current Y coordinate
- * 
- * Checks to see if a mouse drag starting at (@start_x, @start_y) and ending
- * at (@current_x, @current_y) has passed the GTK drag threshold, and thus
- * should trigger the beginning of a drag-and-drop operation.
+ *
+ * Checks to see if a drag movement has passed the GTK drag threshold.
  *
  * Returns: %TRUE if the drag threshold has been passed.
  */