From 22ac6d31482150486e4d7eb5699d81aa88ffac5f Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Thu, 13 Aug 2020 20:59:04 -0400
Subject: [PATCH] gdk: Documentation touchups

Minor rewordings here and there, strip nonpublic
functions of doc comments, deemphasize logical/physical
devices.
---
 gdk/gdkdevice.c | 20 ++++++++++----------
 gdk/gdkseat.c   | 18 +++++++++---------
 2 files changed, 19 insertions(+), 19 deletions(-)

diff --git a/gdk/gdkdevice.c b/gdk/gdkdevice.c
index 3dbc4ec2c4..a6a545656b 100644
--- a/gdk/gdkdevice.c
+++ b/gdk/gdkdevice.c
@@ -35,9 +35,8 @@
  * The #GdkDevice object represents a single input device, such
  * as a keyboard, a mouse, a touchpad, etc.
  *
- * See the #GdkSeat documentation for more information
- * about the various kinds of logical and physical devices, and their
- * relationships.
+ * See the #GdkSeat documentation for more information about the
+ * various kinds of devices, and their relationships.
  */
 
 /**
@@ -536,7 +535,8 @@ gdk_device_get_surface_at_position (GdkDevice *device,
  * gdk_device_get_name:
  * @device: a #GdkDevice
  *
- * Determines the name of the device.
+ * Determines the name of the device, suitable
+ * for showing in a user interface.
  *
  * Returns: a name
  **/
@@ -553,7 +553,8 @@ gdk_device_get_name (GdkDevice *device)
  * @device: a #GdkDevice
  *
  * Determines whether the pointer follows device motion.
- * This is not meaningful for keyboard devices, which don't have a pointer.
+ * This is not meaningful for keyboard devices, which
+ * don't have a pointer.
  *
  * Returns: %TRUE if the pointer follows device motion
  **/
@@ -642,7 +643,7 @@ _gdk_device_set_associated_device (GdkDevice *device,
     device->associated = g_object_ref (associated);
 }
 
-/**
+/*
  * gdk_device_list_physical_devices:
  * @device: a logical #GdkDevice
  *
@@ -681,7 +682,7 @@ _gdk_device_remove_physical_device (GdkDevice *device,
   device->physical_devices = g_list_delete_link (device->physical_devices, elem);
 }
 
-/**
+/*
  * gdk_device_get_n_axes:
  * @device: a pointer #GdkDevice
  *
@@ -698,7 +699,7 @@ gdk_device_get_n_axes (GdkDevice *device)
   return device->axes->len;
 }
 
-/**
+/*
  * gdk_device_get_axis: (skip)
  * @device: a #GdkDevice
  * @axes: (array): pointer to an array of axes
@@ -1194,8 +1195,7 @@ gdk_device_set_seat (GdkDevice *device,
  *
  * Returns the #GdkSeat the device belongs to.
  *
- * Returns: (transfer none): A #GdkSeat. This memory is owned by GTK+ and
- *          must not be freed.
+ * Returns: (transfer none): a #GdkSeat
  **/
 GdkSeat *
 gdk_device_get_seat (GdkDevice *device)
diff --git a/gdk/gdkseat.c b/gdk/gdkseat.c
index a88e8e7785..75ef348a2d 100644
--- a/gdk/gdkseat.c
+++ b/gdk/gdkseat.c
@@ -232,7 +232,7 @@ gdk_seat_get_capabilities (GdkSeat *seat)
   return seat_class->get_capabilities (seat);
 }
 
-/**
+/*
  * gdk_seat_grab:
  * @seat: a #GdkSeat
  * @surface: the #GdkSurface which will own the grab
@@ -306,7 +306,7 @@ gdk_seat_grab (GdkSeat                *seat,
                            event, prepare_func, prepare_func_data);
 }
 
-/**
+/*
  * gdk_seat_ungrab:
  * @seat: a #GdkSeat
  *
@@ -332,7 +332,7 @@ gdk_seat_ungrab (GdkSeat *seat)
  *
  * Returns: (transfer container) (element-type GdkDevice): A list of #GdkDevices.
  *          The list must be freed with g_list_free(), the elements are owned
- *          by GDK and must not be freed.
+ *          by GTK and must not be freed.
  **/
 GList *
 gdk_seat_get_devices (GdkSeat             *seat,
@@ -350,9 +350,9 @@ gdk_seat_get_devices (GdkSeat             *seat,
  * gdk_seat_get_pointer:
  * @seat: a #GdkSeat
  *
- * Returns the logical device that routes pointer events.
+ * Returns the device that routes pointer events.
  *
- * Returns: (transfer none) (nullable): a logical #GdkDevice with pointer
+ * Returns: (transfer none) (nullable): a #GdkDevice with pointer
  *          capabilities. This object is owned by GTK and must not be freed.
  **/
 GdkDevice *
@@ -370,9 +370,9 @@ gdk_seat_get_pointer (GdkSeat *seat)
  * gdk_seat_get_keyboard:
  * @seat: a #GdkSeat
  *
- * Returns the logical device that routes keyboard events.
+ * Returns the device that routes keyboard events.
  *
- * Returns: (transfer none) (nullable): a logical #GdkDevice with keyboard
+ * Returns: (transfer none) (nullable): a #GdkDevice with keyboard
  *          capabilities. This object is owned by GTK and must not be freed.
  **/
 GdkDevice *
@@ -468,8 +468,8 @@ gdk_seat_get_tool (GdkSeat *seat,
  * Returns all #GdkDeviceTools that are known to the
  * application.
  *
- * Returns: (transfer container) (element-type Gdk.DeviceTool): A list of tools. Free with
- * g_list_free().
+ * Returns: (transfer container) (element-type Gdk.DeviceTool):
+ *     A list of tools. Free with g_list_free().
  **/
 GList *
 gdk_seat_get_tools (GdkSeat *seat)