[mutter] clutter/seat: Add gtkDoc comments for touch-mode property

[Carlos Garnacho <carlosg src gnome org>]

commit d7c7311ceb90d0edf10b0924aefffe2f1fa8d956
Author: Jonas Dreßler <verdre v0yd nl>
Date:   Thu Feb 20 21:57:15 2020 +0100

    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)
 {