[gtk: 19/72] Add type annotations for GdkWayland API




commit fe871f9d4626f1bd40103dffc3b8d58c79d0b1f2
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Mon Oct 12 14:04:13 2020 +0100

    Add type annotations for GdkWayland API
    
    The GdkWayland API takes generic GDK types and performs a run time
    check, which means we need to properly annotate the actual expected
    type in order to have methods recognised as such.

 gdk/wayland/gdkdevice-wayland.c  | 11 ++++++-----
 gdk/wayland/gdkdisplay-wayland.c | 25 ++++++++++++++++++++-----
 gdk/wayland/gdksurface-wayland.c | 32 +++++++++++++++++++++++++++-----
 3 files changed, 53 insertions(+), 15 deletions(-)
---
diff --git a/gdk/wayland/gdkdevice-wayland.c b/gdk/wayland/gdkdevice-wayland.c
index 65727857ec..1fb60eadf8 100644
--- a/gdk/wayland/gdkdevice-wayland.c
+++ b/gdk/wayland/gdkdevice-wayland.c
@@ -5029,9 +5029,10 @@ gdk_wayland_seat_get_wl_seat (GdkSeat *seat)
 
 /**
  * gdk_wayland_device_get_node_path:
- * @device: a #GdkDevice
+ * @device: (type GdkWaylandDevice): a #GdkDevice
+ *
+ * Returns the `/dev/input/event*` path of this device.
  *
- * Returns the /dev/input/event* path of this device.
  * For #GdkDevices that possibly coalesce multiple hardware
  * devices (eg. mouse, keyboard, touch,...), this function
  * will return %NULL.
@@ -5039,8 +5040,8 @@ gdk_wayland_seat_get_wl_seat (GdkSeat *seat)
  * This is most notably implemented for devices of type
  * %GDK_SOURCE_PEN, %GDK_SOURCE_TABLET_PAD.
  *
- * Returns: 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)
 {
@@ -5065,7 +5066,7 @@ gdk_wayland_device_get_node_path (GdkDevice *device)
 
 /**
  * gdk_wayland_device_pad_set_feedback:
- * @device: a %GDK_SOURCE_TABLET_PAD device
+ * @device: (type GdkWaylandDevice): a %GDK_SOURCE_TABLET_PAD device
  * @feature: Feature to set the feedback label for
  * @feature_idx: 0-indexed index of the feature to set the feedback label for
  * @label: Feedback label
diff --git a/gdk/wayland/gdkdisplay-wayland.c b/gdk/wayland/gdkdisplay-wayland.c
index dcbd9680f1..b2c182a884 100644
--- a/gdk/wayland/gdkdisplay-wayland.c
+++ b/gdk/wayland/gdkdisplay-wayland.c
@@ -384,6 +384,15 @@ static const struct org_kde_kwin_server_decoration_manager_listener server_decor
   .default_mode = server_decoration_manager_default_mode
 };
 
+/**
+ * gdk_wayland_display_prefers_ssd:
+ * @display: (type GdkWaylandDisplay): a #GdkDisplay
+ *
+ * Checks whether the Wayland compositor prefers to draw the window
+ * decorations or if it leaves decorations to the application.
+ *
+ * Returns: %TRUE if the compositor prefers server-side decorations
+ */
 gboolean
 gdk_wayland_display_prefers_ssd (GdkDisplay *display)
 {
@@ -859,7 +868,7 @@ gdk_wayland_display_get_next_serial (GdkDisplay *display)
 
 /**
  * gdk_wayland_display_get_startup_notification_id:
- * @display: (type GdkX11Display): a #GdkDisplay
+ * @display: (type GdkWaylandDisplay): a #GdkDisplay
  *
  * Gets the startup notification ID for a Wayland display, or %NULL
  * if no ID has been defined.
@@ -1064,10 +1073,16 @@ get_cursor_theme (GdkWaylandDisplay *display_wayland,
   return wl_cursor_theme_create ("/usr/share/icons/default/cursors", size, display_wayland->shm);
 }
 
+/**
+ * gdk_wayland_display_set_cursor_theme:
+ * @display: (type GdkWaylandDisplay): a #GdkDisplay
+ *
+ * Sets the cursor theme for the given @display.
+ */
 void
-gdk_wayland_display_set_cursor_theme (GdkDisplay  *display,
+gdk_wayland_display_set_cursor_theme (GdkDisplay *display,
                                       const char *name,
-                                      int          size)
+                                      int         size)
 {
   GdkWaylandDisplay *display_wayland = GDK_WAYLAND_DISPLAY(display);
   struct wl_cursor_theme *theme;
@@ -2617,11 +2632,11 @@ gdk_wayland_display_get_output_scale (GdkWaylandDisplay *display_wayland,
 
 /**
  * gdk_wayland_display_query_registry:
- * @display: a wayland #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.
+ * `wl_registry.global` handler.
  *
  * Returns: %TRUE if the global is offered by the compositor
  **/
diff --git a/gdk/wayland/gdksurface-wayland.c b/gdk/wayland/gdksurface-wayland.c
index d7ff188e7d..0d8fe2fe74 100644
--- a/gdk/wayland/gdksurface-wayland.c
+++ b/gdk/wayland/gdksurface-wayland.c
@@ -1694,6 +1694,13 @@ create_zxdg_toplevel_v6_resources (GdkSurface *surface)
                                  surface);
 }
 
+/**
+ * gdk_wayland_toplevel_set_application_id:
+ * @toplevel: (type GdkWaylandToplevel): a #GdkToplevel
+ * @application_id: the application id for the @toplevel
+ *
+ * Sets the application id on a #GdkToplevel.
+ */
 void
 gdk_wayland_toplevel_set_application_id (GdkToplevel *toplevel,
                                          const char  *application_id)
@@ -4225,12 +4232,12 @@ static const struct zxdg_exported_v1_listener xdg_exported_listener = {
 
 /**
  * GdkWaylandToplevelExported:
- * @toplevel: 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()
  *
  * Callback that gets called when the handle for a surface has been
- * obtained from the Wayland compositor. The handle can be passed
+ * 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.
  */
@@ -4243,7 +4250,7 @@ gdk_wayland_surface_is_exported (GdkWaylandSurface *impl)
 
 /**
  * gdk_wayland_toplevel_export_handle:
- * @toplevel: 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
@@ -4307,7 +4314,7 @@ gdk_wayland_toplevel_export_handle (GdkToplevel                *toplevel,
 
 /**
  * gdk_wayland_toplevel_unexport_handle:
- * @toplevel: the #GdkToplevel to unexport
+ * @toplevel: (type GdkWaylandToplevel): the #GdkToplevel to unexport
  *
  * Destroys the handle that was obtained with
  * gdk_wayland_toplevel_export_handle().
@@ -4361,7 +4368,7 @@ static const struct zxdg_imported_v1_listener xdg_imported_listener = {
 
 /**
  * gdk_wayland_toplevel_set_transient_for_exported:
- * @toplevel: 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
@@ -4414,6 +4421,13 @@ gdk_wayland_surface_get_inhibitor (GdkWaylandSurface *impl,
   return g_hash_table_lookup (impl->shortcuts_inhibitors, gdk_seat);
 }
 
+/*
+ * gdk_wayland_surface_inhibit_shortcuts:
+ * @surface: (type GdkWaylandSurface): a #GdkSurface
+ * @seat: the seat to inhibit
+ *
+ * Inhibits the shortcuts coming from the given @seat.
+ */
 void
 gdk_wayland_surface_inhibit_shortcuts (GdkSurface *surface,
                                        GdkSeat    *gdk_seat)
@@ -4437,6 +4451,14 @@ gdk_wayland_surface_inhibit_shortcuts (GdkSurface *surface,
   g_hash_table_insert (impl->shortcuts_inhibitors, gdk_seat, inhibitor);
 }
 
+/*
+ * gdk_wayland_surface_restore_shortcuts:
+ * @surface: (type GdkWaylandSurface): a #GdkSurface
+ * @seat: the seat to inhibit
+ *
+ * Restores the shortcuts on the given @seat inhibited by calling
+ * gdk_wayland_surface_inhibit_shortcuts().
+ */
 void
 gdk_wayland_surface_restore_shortcuts (GdkSurface *surface,
                                        GdkSeat    *gdk_seat)


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]