[gtk/ebassi/gidocgen: 76/483] docs: Brush up the Wayland backend docs

[Emmanuele Bassi <ebassi src gnome org>]

commit b0cd9e6943f2826abfb2713b676725b5b7dbddaf
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Feb 21 10:40:24 2021 -0500

    docs: Brush up the Wayland backend docs
    
    Add some content here.

 gdk/wayland/gdkdevice-wayland.c    | 72 +++++++++++++++++++++++++++-----------
 gdk/wayland/gdkdisplay-wayland.c   | 42 ++++++++++++++--------
 gdk/wayland/gdkglcontext-wayland.c |  6 ++++
 gdk/wayland/gdkmonitor-wayland.c   | 16 +++++++--
 gdk/wayland/gdksurface-wayland.c   | 71 +++++++++++++++++++++++++++----------
 5 files changed, 150 insertions(+), 57 deletions(-)
---
diff --git a/gdk/wayland/gdkdevice-wayland.c b/gdk/wayland/gdkdevice-wayland.c
index 4692224233..712fcd2a98 100644
--- a/gdk/wayland/gdkdevice-wayland.c
+++ b/gdk/wayland/gdkdevice-wayland.c
@@ -54,6 +54,28 @@
 #include <linux/input.h>
 #endif
 
+/**
+ * GdkWaylandDevice:
+ *
+ * The Wayland implementation of `GdkDevice`.
+ *
+ * Beyond the regular [class@Gdk.Device] API, the Wayland implementation
+ * provides access to Wayland objects such as the `wl_seat` with
+ * [method@GdkWayland.WaylandDevice.get_wl_seat], the `wl_keyboard` with
+ * [method@GdkWayland.WaylandDevice.get_wl_keyboard] and the `wl_pointer` with
+ * [method@GdkWayland.WaylandDevice.get_wl_pointer].
+ */
+
+/**
+ * GdkWaylandSeat:
+ *
+ * The Wayland implementation of `GdkSeat`.
+ *
+ * Beyond the regular [class Gdk Seat] API, the Wayland implementation
+ * provides access to the Wayland `wl_seat` object with
+ * [method@GdkWayland.WaylandSeat.get_wl_seat].
+ */
+
 #define BUTTON_BASE (BTN_LEFT - 1) /* Used to translate to 1-indexed buttons */
 
 #ifndef BTN_STYLUS3
@@ -945,11 +967,11 @@ gdk_wayland_device_pad_init (GdkWaylandDevicePad *pad)
 
 /**
  * gdk_wayland_device_get_wl_seat: (skip)
- * @device: (type GdkWaylandDevice): a #GdkDevice
+ * @device: (type GdkWaylandDevice): a `GdkDevice`
  *
- * Returns the Wayland wl_seat of a #GdkDevice.
+ * Returns the Wayland `wl_seat` of a `GdkDevice`.
  *
- * Returns: (transfer none): a Wayland wl_seat
+ * Returns: (transfer none): a Wayland `wl_seat`
  */
 struct wl_seat *
 gdk_wayland_device_get_wl_seat (GdkDevice *device)
@@ -964,11 +986,11 @@ gdk_wayland_device_get_wl_seat (GdkDevice *device)
 
 /**
  * gdk_wayland_device_get_wl_pointer: (skip)
- * @device: (type GdkWaylandDevice): a #GdkDevice
+ * @device: (type GdkWaylandDevice): a `GdkDevice`
  *
- * Returns the Wayland wl_pointer of a #GdkDevice.
+ * Returns the Wayland `wl_pointer` of a `GdkDevice`.
  *
- * Returns: (transfer none): a Wayland wl_pointer
+ * Returns: (transfer none): a Wayland `wl_pointer`
  */
 struct wl_pointer *
 gdk_wayland_device_get_wl_pointer (GdkDevice *device)
@@ -983,11 +1005,11 @@ gdk_wayland_device_get_wl_pointer (GdkDevice *device)
 
 /**
  * gdk_wayland_device_get_wl_keyboard: (skip)
- * @device: (type GdkWaylandDevice): a #GdkDevice
+ * @device: (type GdkWaylandDevice): a `GdkDevice`
  *
- * Returns the Wayland wl_keyboard of a #GdkDevice.
+ * Returns the Wayland `wl_keyboard` of a `GdkDevice`.
  *
- * Returns: (transfer none): a Wayland wl_keyboard
+ * Returns: (transfer none): a Wayland `wl_keyboard`
  */
 struct wl_keyboard *
 gdk_wayland_device_get_wl_keyboard (GdkDevice *device)
@@ -5033,9 +5055,11 @@ gdk_wayland_seat_set_drag (GdkSeat *seat,
 
 /**
  * gdk_wayland_device_get_data_device: (skip)
- * @gdk_device: (type GdkWaylandDevice): a #GdkDevice
+ * @gdk_device: (type GdkWaylandDevice): a `GdkDevice`
+ *
+ * Returns the Wayland `wl_data_device` of a `GdkDevice`.
  *
- * ...
+ * Returns: (transfer none): a Wayland `wl_data_device`
  */
 struct wl_data_device *
 gdk_wayland_device_get_data_device (GdkDevice *gdk_device)
@@ -5050,10 +5074,13 @@ gdk_wayland_device_get_data_device (GdkDevice *gdk_device)
 
 /**
  * gdk_wayland_device_set_selection: (skip)
- * @gdk_device: (type GdkWaylandDevice): a #GdkDevice
+ * @gdk_device: (type GdkWaylandDevice): a `GdkDevice`
  * @source: the data source for the selection
  *
- * ...
+ * Sets the selection of the `GdkDevice.
+ *
+ * This is calling wl_data_device_set_selection() on
+ * the `wl_data_device` of @gdk_device.
  */
 void
 gdk_wayland_device_set_selection (GdkDevice             *gdk_device,
@@ -5073,9 +5100,9 @@ gdk_wayland_device_set_selection (GdkDevice             *gdk_device,
 
 /**
  * gdk_wayland_seat_get_wl_seat: (skip)
- * @seat: (type GdkWaylandSeat): a #GdkSeat
+ * @seat: (type GdkWaylandSeat): a `GdkSeat`
  *
- * Returns the Wayland `wl_seat` of a #GdkSeat.
+ * Returns the Wayland `wl_seat` of a `GdkSeat`.
  *
  * Returns: (transfer none): a Wayland `wl_seat`
  */
@@ -5089,18 +5116,19 @@ gdk_wayland_seat_get_wl_seat (GdkSeat *seat)
 
 /**
  * gdk_wayland_device_get_node_path:
- * @device: (type GdkWaylandDevice): a #GdkDevice
+ * @device: (type GdkWaylandDevice): a `GdkDevice`
  *
  * Returns the `/dev/input/event*` path of this device.
  *
- * For #GdkDevices that possibly coalesce multiple hardware
+ * For `GdkDevice`s that possibly coalesce multiple hardware
  * devices (eg. mouse, keyboard, touch,...), this function
  * will return %NULL.
  *
  * This is most notably implemented for devices of type
  * %GDK_SOURCE_PEN, %GDK_SOURCE_TABLET_PAD.
  *
- * Returns: (nullable) (transfer none): the `/dev/input/event*` path of this device
+ * Returns: (nullable) (transfer none): the `/dev/input/event*`
+ *   path of this device
  */
 const char *
 gdk_wayland_device_get_node_path (GdkDevice *device)
@@ -5131,9 +5159,11 @@ gdk_wayland_device_get_node_path (GdkDevice *device)
  * @feature_idx: 0-indexed index of the feature to set the feedback label for
  * @label: Feedback label
  *
- * Sets the feedback label for the given feature/index. This may be used by the
- * compositor to provide user feedback of the actions available/performed.
- **/
+ * Sets the feedback label for the given feature/index.
+ *
+ * This may be used by the compositor to provide user feedback
+ * of the actions available/performed.
+ */
 void
 gdk_wayland_device_pad_set_feedback (GdkDevice           *device,
                                      GdkDevicePadFeature  feature,
diff --git a/gdk/wayland/gdkdisplay-wayland.c b/gdk/wayland/gdkdisplay-wayland.c
index 673c9d3478..03a38be862 100644
--- a/gdk/wayland/gdkdisplay-wayland.c
+++ b/gdk/wayland/gdkdisplay-wayland.c
@@ -58,6 +58,20 @@
 
 #include "gdk/gdk-private.h"
 
+/**
+ * GdkWaylandDisplay:
+ *
+ * The Wayland implementation of `GdkDisplay`.
+ *
+ * Beyond the regular [class@Gdk.Display] API, the Wayland implementation
+ * provides access to Wayland objects such as the `wl_display` with
+ * [method@GdkWayland.WaylandDisplay.get_wl_display], the `wl_compositor` with
+ * [method@GdkWayland.WaylandDisplay.get_wl_compositor].
+ *
+ * You can find out what Wayland globals are supported by a display
+ * with [method@GdkWayland.WaylandDisplay.query_registry].
+ */
+
 #define MIN_SYSTEM_BELL_DELAY_MS 20
 
 #define GTK_SHELL1_VERSION       4
@@ -876,7 +890,7 @@ gdk_wayland_display_get_next_serial (GdkDisplay *display)
 
 /**
  * gdk_wayland_display_get_startup_notification_id:
- * @display: (type GdkWaylandDisplay): a #GdkDisplay
+ * @display: (type GdkWaylandDisplay): a `GdkDisplay`
  *
  * Gets the startup notification ID for a Wayland display, or %NULL
  * if no ID has been defined.
@@ -891,19 +905,19 @@ gdk_wayland_display_get_startup_notification_id (GdkDisplay  *display)
 
 /**
  * gdk_wayland_display_set_startup_notification_id:
- * @display: (type GdkWaylandDisplay): a #GdkDisplay
+ * @display: (type GdkWaylandDisplay): a `GdkDisplay`
  * @startup_id: the startup notification ID (must be valid utf8)
  *
  * Sets the startup notification ID for a display.
  *
- * This is usually taken from the value of the DESKTOP_STARTUP_ID
+ * This is usually taken from the value of the `DESKTOP_STARTUP_ID`
  * environment variable, but in some cases (such as the application not
  * being launched using exec()) it can come from other sources.
  *
  * The startup ID is also what is used to signal that the startup is
  * complete (for example, when opening a window or when calling
- * gdk_display_notify_startup_complete()).
- **/
+ * [method@Gdk.Display.notify_startup_complete]).
+ */
 void
 gdk_wayland_display_set_startup_notification_id (GdkDisplay *display,
                                                  const char *startup_id)
@@ -1083,7 +1097,7 @@ get_cursor_theme (GdkWaylandDisplay *display_wayland,
 
 /**
  * gdk_wayland_display_set_cursor_theme:
- * @display: (type GdkWaylandDisplay): a #GdkDisplay
+ * @display: (type GdkWaylandDisplay): a `GdkDisplay`
  * @name: the new cursor theme
  * @size: the size to use for cursors
  *
@@ -1180,11 +1194,11 @@ _gdk_wayland_display_update_serial (GdkWaylandDisplay *display_wayland,
 
 /**
  * gdk_wayland_display_get_wl_display: (skip)
- * @display: (type GdkWaylandDisplay): a #GdkDisplay
+ * @display: (type GdkWaylandDisplay): a `GdkDisplay`
  *
- * Returns the Wayland wl_display of a #GdkDisplay.
+ * Returns the Wayland `wl_display` of a `GdkDisplay`.
  *
- * Returns: (transfer none): a Wayland wl_display
+ * Returns: (transfer none): a Wayland `wl_display`
  */
 struct wl_display *
 gdk_wayland_display_get_wl_display (GdkDisplay *display)
@@ -1196,11 +1210,11 @@ gdk_wayland_display_get_wl_display (GdkDisplay *display)
 
 /**
  * gdk_wayland_display_get_wl_compositor: (skip)
- * @display: (type GdkWaylandDisplay): a #GdkDisplay
+ * @display: (type GdkWaylandDisplay): a `GdkDisplay`
  *
- * Returns the Wayland global singleton compositor of a #GdkDisplay.
+ * Returns the Wayland `wl_compositor` of a `GdkDisplay`.
  *
- * Returns: (transfer none): a Wayland wl_compositor
+ * Returns: (transfer none): a Wayland `wl_compositor`
  */
 struct wl_compositor *
 gdk_wayland_display_get_wl_compositor (GdkDisplay *display)
@@ -2639,14 +2653,14 @@ gdk_wayland_display_get_output_scale (GdkWaylandDisplay *display_wayland,
 
 /**
  * gdk_wayland_display_query_registry:
- * @display: (type GdkWaylandDisplay): a #GdkDisplay
+ * @display: (type GdkWaylandDisplay): a `GdkDisplay`
  * @global: global interface to query in the registry
  *
  * Returns %TRUE if the the interface was found in the display
  * `wl_registry.global` handler.
  *
  * Returns: %TRUE if the global is offered by the compositor
- **/
+ */
 gboolean
 gdk_wayland_display_query_registry (GdkDisplay  *display,
                                    const char *global)
diff --git a/gdk/wayland/gdkglcontext-wayland.c b/gdk/wayland/gdkglcontext-wayland.c
index a5939416f8..1667117e7f 100644
--- a/gdk/wayland/gdkglcontext-wayland.c
+++ b/gdk/wayland/gdkglcontext-wayland.c
@@ -35,6 +35,12 @@
 
 #include "gdkintl.h"
 
+/**
+ * GdkWaylandGLContext:
+ *
+ * The Wayland implementation of `GdkGLContext`.
+ */
+
 G_DEFINE_TYPE (GdkWaylandGLContext, gdk_wayland_gl_context, GDK_TYPE_GL_CONTEXT)
 
 static void gdk_wayland_gl_context_dispose (GObject *gobject);
diff --git a/gdk/wayland/gdkmonitor-wayland.c b/gdk/wayland/gdkmonitor-wayland.c
index e13a686055..165078df07 100644
--- a/gdk/wayland/gdkmonitor-wayland.c
+++ b/gdk/wayland/gdkmonitor-wayland.c
@@ -23,6 +23,16 @@
 
 #include "gdkmonitor-wayland.h"
 
+/**
+ * GdkWaylandMonitor:
+ *
+ * The Wayland implementation of `GdkMonitor`.
+ *
+ * Beyond the [class@Gdk.Monitor] API, the Wayland implementation
+ * offers access to the Wayland `wl_output` object with
+ * [method@GdkWayland.WaylandMonitor.get_wl_output].
+ */
+
 G_DEFINE_TYPE (GdkWaylandMonitor, gdk_wayland_monitor, GDK_TYPE_MONITOR)
 
 static void
@@ -50,11 +60,11 @@ gdk_wayland_monitor_class_init (GdkWaylandMonitorClass *class)
 
 /**
  * gdk_wayland_monitor_get_wl_output: (skip)
- * @monitor: (type GdkWaylandMonitor): a #GdkMonitor
+ * @monitor: (type GdkWaylandMonitor): a `GdkMonitor`
  *
- * Returns the Wayland wl_output of a #GdkMonitor.
+ * Returns the Wayland `wl_output` of a `GdkMonitor`.
  *
- * Returns: (transfer none): a Wayland wl_output
+ * Returns: (transfer none): a Wayland `wl_output`
  */
 struct wl_output *
 gdk_wayland_monitor_get_wl_output (GdkMonitor *monitor)
diff --git a/gdk/wayland/gdksurface-wayland.c b/gdk/wayland/gdksurface-wayland.c
index 2f95339fb0..1e25d98662 100644
--- a/gdk/wayland/gdksurface-wayland.c
+++ b/gdk/wayland/gdksurface-wayland.c
@@ -43,6 +43,33 @@
 #include <netinet/in.h>
 #include <unistd.h>
 
+/**
+ * GdkWaylandSurface:
+ *
+ * The Wayland implementation of `GdkSurface`.
+ *
+ * Beyond the [class@Gdk.Surface] API, the Wayland implementation offers
+ * access to the Wayland `wl_surface` object with
+ * [method@GdkWayland.WaylandSurface.get_wl_surface].
+ */
+
+/**
+ * GdkWaylandToplevel:
+ *
+ * The Wayland implementation of `GdkToplevel`.
+ *
+ * Beyond the [interface@Gdk.Toplevel] API, the Wayland implementation
+ * has API to set up cross-process parent-child relationships between
+ * surfaces with [method@GdkWayland.WaylandToplevel.export_handle] and
+ * [method@GdkWayland.WaylandToplevel.set_transient_for_exported].
+ */
+
+/**
+ * GdkWaylandPopup:
+ *
+ * The Wayland implementation of `GdkPopup`.
+ */
+
 #define SURFACE_IS_TOPLEVEL(surface)  TRUE
 
 #define MAX_WL_BUFFER_SIZE (4083) /* 4096 minus header, string argument length and NUL byte */
@@ -1878,10 +1905,10 @@ create_zxdg_toplevel_v6_resources (GdkSurface *surface)
 
 /**
  * gdk_wayland_toplevel_set_application_id:
- * @toplevel: (type GdkWaylandToplevel): a #GdkToplevel
+ * @toplevel: (type GdkWaylandToplevel): a `GdkToplevel`
  * @application_id: the application id for the @toplevel
  *
- * Sets the application id on a #GdkToplevel.
+ * Sets the application id on a `GdkToplevel`.
  */
 void
 gdk_wayland_toplevel_set_application_id (GdkToplevel *toplevel,
@@ -4238,11 +4265,11 @@ _gdk_wayland_surface_set_grab_seat (GdkSurface *surface,
 
 /**
  * gdk_wayland_surface_get_wl_surface: (skip)
- * @surface: (type GdkWaylandSurface): a #GdkSurface
+ * @surface: (type GdkWaylandSurface): a `GdkSurface`
  *
- * Returns the Wayland surface of a #GdkSurface.
+ * Returns the Wayland `wl_surface` of a `GdkSurface`.
  *
- * Returns: (transfer none): a Wayland wl_surface
+ * Returns: (transfer none): a Wayland `wl_surface`
  */
 struct wl_surface *
 gdk_wayland_surface_get_wl_surface (GdkSurface *surface)
@@ -4429,14 +4456,17 @@ static const struct zxdg_exported_v1_listener xdg_exported_listener = {
 
 /**
  * GdkWaylandToplevelExported:
- * @toplevel: (type GdkWaylandToplevel): the #GdkToplevel that is exported
+ * @toplevel: (type GdkWaylandToplevel): the `GdkToplevel` that is exported
  * @handle: the handle
- * @user_data: user data that was passed to gdk_wayland_toplevel_export_handle()
+ * @user_data: user data that was passed to [method@GdkWayland.WaylandToplevel.export_handle]
  *
  * Callback that gets called when the handle for a surface has been
- * obtained from the Wayland compositor. The @handle can be passed
- * to other processes, for the purpose of marking surfaces as transient
- * for out-of-process surfaces.
+ * obtained from the Wayland compositor.
+ *
+ * This callback is used in [method@GdkWayland.WaylandToplevel.export_handle].
+ *
+ * The @handle can be passed to other processes, for the purpose of
+ * marking surfaces as transient for out-of-process surfaces.
  */
 
 static gboolean
@@ -4447,24 +4477,25 @@ gdk_wayland_surface_is_exported (GdkWaylandSurface *impl)
 
 /**
  * gdk_wayland_toplevel_export_handle:
- * @toplevel: (type GdkWaylandToplevel): the #GdkToplevel to obtain a handle for
+ * @toplevel: (type GdkWaylandToplevel): the `GdkToplevel` to obtain a handle for
  * @callback: callback to call with the handle
  * @user_data: (closure): user data for @callback
  * @destroy_func: destroy notify for @user_data
  *
  * Asynchronously obtains a handle for a surface that can be passed
- * to other processes. When the handle has been obtained, @callback
- * will be called.
+ * to other processes.
+ *
+ * When the handle has been obtained, @callback will be called.
  *
  * It is an error to call this function on a surface that is already
  * exported.
  *
- * When the handle is no longer needed, gdk_wayland_toplevel_unexport_handle()
+ * When the handle is no longer needed, [method@GdkWayland.WaylandToplevel.unexport_handle]
  * should be called to clean up resources.
  *
  * The main purpose for obtaining a handle is to mark a surface
  * from another surface as transient for this one, see
- * gdk_wayland_toplevel_set_transient_for_exported().
+ * [method@GdkWayland.WaylandToplevel.set_transient_for_exported].
  *
  * Note that this API depends on an unstable Wayland protocol,
  * and thus may require changes in the future.
@@ -4511,7 +4542,7 @@ gdk_wayland_toplevel_export_handle (GdkToplevel                *toplevel,
 
 /**
  * gdk_wayland_toplevel_unexport_handle:
- * @toplevel: (type GdkWaylandToplevel): the #GdkToplevel to unexport
+ * @toplevel: (type GdkWaylandToplevel): the `GdkToplevel` to unexport
  *
  * Destroys the handle that was obtained with
  * gdk_wayland_toplevel_export_handle().
@@ -4565,12 +4596,14 @@ static const struct zxdg_imported_v1_listener xdg_imported_listener = {
 
 /**
  * gdk_wayland_toplevel_set_transient_for_exported:
- * @toplevel: (type GdkWaylandToplevel): the #GdkToplevel to make as transient
+ * @toplevel: (type GdkWaylandToplevel): the `GdkToplevel` to make as transient
  * @parent_handle_str: an exported handle for a surface
  *
  * Marks @toplevel as transient for the surface to which the given
- * @parent_handle_str refers. Typically, the handle will originate
- * from a gdk_wayland_toplevel_export_handle() call in another process.
+ * @parent_handle_str refers.
+ *
+ * Typically, the handle will originate from a
+ * [method@WaylandToplevel.export_handle] call in another process.
  *
  * Note that this API depends on an unstable Wayland protocol,
  * and thus may require changes in the future.