From d7c7311ceb90d0edf10b0924aefffe2f1fa8d956 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jonas=20Dre=C3=9Fler?= <verdre@v0yd.nl>
Date: Thu, 20 Feb 2020 21:57:15 +0100
Subject: [PATCH] clutter/seat: Add gtkDoc comments for touch-mode property

It's not that easy to find out when the touch-mode is enabled without
reading the code, so document that.

https://gitlab.gnome.org/GNOME/mutter/merge_requests/1075
---
 clutter/clutter/clutter-seat.c | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/clutter/clutter/clutter-seat.c b/clutter/clutter/clutter-seat.c
index 9350bfd11..c383a2035 100644
--- a/clutter/clutter/clutter-seat.c
+++ b/clutter/clutter/clutter-seat.c
@@ -282,6 +282,12 @@ clutter_seat_class_init (ClutterSeatClass *klass)
                          CLUTTER_TYPE_BACKEND,
                          CLUTTER_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY);
 
+  /**
+   * ClutterSeat:touch-mode:
+   *
+   * The current touch-mode of the #ClutterSeat, it is set to %TRUE if the
+   * requirements documented in clutter_seat_get_touch_mode() are fulfilled.
+   **/
   props[PROP_TOUCH_MODE] =
     g_param_spec_boolean ("touch-mode",
                           P_("Touch mode"),
@@ -569,6 +575,21 @@ clutter_seat_warp_pointer (ClutterSeat *seat,
   CLUTTER_SEAT_GET_CLASS (seat)->warp_pointer (seat, x, y);
 }
 
+/**
+ * clutter_seat_get_touch_mode:
+ * @seat: a #ClutterSeat
+ *
+ * Gets the current touch-mode state of the #ClutterSeat @seat.
+ * The #ClutterSeat:touch-mode property is set to %TRUE if the following
+ * requirements are fulfilled:
+ *
+ *  - A touchscreen is available
+ *  - No external keyboard is attached to the device
+ *  - A tablet mode switch, if present, is enabled
+ *
+ * Returns: %TRUE if the device is a tablet that doesn't have an external
+ *   keyboard attached, %FALSE otherwise.
+ **/
 gboolean
 clutter_seat_get_touch_mode (ClutterSeat *seat)
 {