Merge branch 'docs-fixes' into 'master'

Various documentation fixes

See merge request GNOME/gtk!1481

gdk/gdkapplaunchcontext.c

@@ -179,7 +179,7 @@ gdk_app_launch_context_get_display_name (GAppLaunchContext *context,
  *
  * Gets the #GdkDispolat that @context is for.
  *
- * Returns: the display of @context
+ * Returns: (transfer none): the display of @context
  */
 GdkDisplay *
 gdk_app_launch_context_get_display (GdkAppLaunchContext *context)

gdk/gdkcontentproviderimpl.c

@@ -390,7 +390,7 @@ gdk_content_provider_union_init (GdkContentProviderUnion *self)
 
 /**
  * gdk_content_provider_new_union:
- * @providers: (nullable) (array length=n_providers) [transfer elements]:
+ * @providers: (nullable) (array length=n_providers) (transfer full):
  *     The #GdkContentProviders to present the union of
  * @n_providers: the number of providers
  *

gdk/gdkdevice.c

@@ -1681,6 +1681,14 @@ gdk_device_update_tool (GdkDevice     *device,
     }
 }
 
+/**
+ * gdk_device_get_num_touches:
+ * @device: a #GdkDevice
+ *
+ * Retrieves the number of touch points associated to @device.
+ *
+ * Returns: the number of touch points
+ */
 guint
 gdk_device_get_num_touches (GdkDevice *device)
 {
@@ -1689,6 +1697,14 @@ gdk_device_get_num_touches (GdkDevice *device)
   return device->num_touches;
 }
 
+/**
+ * gdk_device_get_device_tool:
+ * @device: a #GdkDevice
+ *
+ * Retrieves the #GdkDeviceTool associated to @device.
+ *
+ * Returns: (transfer none): the #GdkDeviceTool
+ */
 GdkDeviceTool *
 gdk_device_get_device_tool (GdkDevice *device)
 {

gdk/gdkevents.c

@@ -2101,7 +2101,7 @@ gdk_drag_event_get_drop (GdkEvent *event)
  *
  * Extracts the grab surface from a grab broken event.
  *
- * Returns: the grab surface of @event
+ * Returns: (transfer none): the grab surface of @event
  **/
 GdkSurface *
 gdk_grab_broken_event_get_grab_surface (GdkEvent *event)

gtk/gtkdropcontrollermotion.c

@@ -367,7 +367,8 @@ gtk_drop_controller_motion_contains_pointer (GtkDropControllerMotion *self)
  *
  * Returns the value of the GtkDropControllerMotion:drop property.
  *
- * Returns: The #GdkDrop currently happening within @self or %NULL if none
+ * Returns: (transfer none) (nullable): The #GdkDrop currently happening
+ *   within @self or %NULL if none
  */
 GdkDrop *
 gtk_drop_controller_motion_get_drop (GtkDropControllerMotion *self)

gtk/gtkicontheme.c

@@ -1459,9 +1459,9 @@ gtk_icon_theme_set_search_path (GtkIconTheme       *self,
  *
  * Gets the current search path. See gtk_icon_theme_set_search_path().
  * 
- * Returns: (element-type filename):
- *     a list of icon theme path directories or %NULL.
- *     The returned value should be freed with g_strfreev().
+ * Returns: (transfer full) (array zero-terminated=1) (element-type filename) (nullable):
+ *   a list of icon theme path directories or %NULL.
+ *   The returned value should be freed with g_strfreev().
  */
 char **
 gtk_icon_theme_get_search_path (GtkIconTheme  *self)
@@ -1552,8 +1552,9 @@ gtk_icon_theme_set_resource_path (GtkIconTheme       *self,
  *
  * See gtk_icon_theme_set_resource_path().
  * 
- * Returns: A list of resource paths or %NULL.
- *     The returned value should be freed with g_strfreev().
+ * Returns: (transfer full) (array zero-terminated=1) (element-type utf8) (nullable):
+ *   A list of resource paths or %NULL.
+ *   The returned value should be freed with g_strfreev().
  */
 char **
 gtk_icon_theme_get_resource_path (GtkIconTheme  *self)

gtk/gtkstatusbar.c

@@ -502,7 +502,7 @@ gtk_statusbar_remove_all (GtkStatusbar *statusbar,
     }
 }
 
-/** < private >
+/* < private >
  * gtk_statusbar_get_message_area:
  * @statusbar: a #GtkStatusbar
  *

gtk/gtktreednd.c

@@ -260,8 +260,8 @@ G_DEFINE_BOXED_TYPE (GtkTreeRowData, gtk_tree_row_data,
  * 
  * Creates a content provider for dragging @path from @tree_model.
  * 
- * Returns: a new #GdkContentProvider
- **/
+ * Returns: (transfer full): a new #GdkContentProvider
+ */
 GdkContentProvider *
 gtk_tree_create_row_drag_content (GtkTreeModel *tree_model,
 			          GtkTreePath  *path)