cursor-tracker: Enhance the documentation and increase annotation coverage

Add the (optional) parameters when they are actually supported and at least add
the minimal documentation on functions.

Part-of: <https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/2951>

2 files changed, 27 insertions, 10 deletions

diff --git a/clutter/clutter/clutter-seat.c b/clutter/clutter/clutter-seat.c
index 956907b42..1c057325b 100644
--- a/clutter/clutter/clutter-seat.c
+++ b/clutter/clutter/clutter-seat.c
@@ -679,6 +679,17 @@ clutter_seat_has_touchscreen (ClutterSeat *seat)
   return has_touchscreen;
 }
 
+/**
+ * clutter_seat_query_state:
+ * @seat: a #ClutterSeat
+ * @device: a #ClutterInputDevice
+ * @sequence: (nullable): a #ClutterEventSequence
+ * @coords: (out caller-allocates) (optional): the coordinates of the pointer
+ * @modifiers: (out) (optional): the current #ClutterModifierType of the pointer
+ *
+ * Returns: %TRUE if @device (or the specific @sequence) is on the stage, %FALSE
+ *   otherwise.
+ **/
 gboolean
 clutter_seat_query_state (ClutterSeat          *seat,
                           ClutterInputDevice   *device,
diff --git a/src/backends/meta-cursor-tracker.c b/src/backends/meta-cursor-tracker.c
index e6a1d0ba8..f7815e567 100644
--- a/src/backends/meta-cursor-tracker.c
+++ b/src/backends/meta-cursor-tracker.c
@@ -319,7 +319,7 @@ meta_cursor_tracker_class_init (MetaCursorTrackerClass *klass)
  *
  * Retrieves the cursor tracker object for @display.
  *
- * Returns: (transfer none):
+ * Returns: (transfer none): the cursor tracker object for @display.
  */
 MetaCursorTracker *
 meta_cursor_tracker_get_for_display (MetaDisplay *display)
@@ -350,8 +350,11 @@ set_window_cursor (MetaCursorTracker *tracker,
 
 /**
  * meta_cursor_tracker_get_sprite:
+ * @tracker: a #MetaCursorTracker
  *
- * Returns: (transfer none):
+ * Get the #CoglTexture of the cursor sprite
+ *
+ * Returns: (transfer none) (nullable): the #CoglTexture of the cursor sprite
  */
 CoglTexture *
 meta_cursor_tracker_get_sprite (MetaCursorTracker *tracker)
@@ -369,9 +372,11 @@ meta_cursor_tracker_get_sprite (MetaCursorTracker *tracker)
 
 /**
  * meta_cursor_tracker_get_scale:
- * @tracker:
+ * @tracker: a #MetaCursorTracker
+ *
+ * Get the scale factor of the cursor sprite
  *
- * Returns:
+ * Returns: The scale factor of the cursor sprite
  */
 float
 meta_cursor_tracker_get_scale (MetaCursorTracker *tracker)
@@ -388,10 +393,11 @@ meta_cursor_tracker_get_scale (MetaCursorTracker *tracker)
 
 /**
  * meta_cursor_tracker_get_hot:
- * @tracker:
- * @x: (out):
- * @y: (out):
+ * @tracker: a #MetaCursorTracker
+ * @x: (out): the x coordinate of the cursor hotspot
+ * @y: (out): the y coordinate of the cursor hotspot
  *
+ * Get the hotspot of the current cursor sprite.
  */
 void
 meta_cursor_tracker_get_hot (MetaCursorTracker *tracker,
@@ -431,7 +437,7 @@ meta_cursor_tracker_unset_window_cursor (MetaCursorTracker *tracker)
 /**
  * meta_cursor_tracker_set_root_cursor:
  * @tracker: a #MetaCursorTracker object.
- * @cursor_sprite: (transfer none): the new root cursor
+ * @cursor_sprite: (transfer none) (nullable): the new root cursor
  *
  * Sets the root cursor (the cursor that is shown if not modified by a window).
  * The #MetaCursorTracker will take a strong reference to the sprite.
@@ -459,8 +465,8 @@ meta_cursor_tracker_invalidate_position (MetaCursorTracker *tracker)
 /**
  * meta_cursor_tracker_get_pointer:
  * @tracker: a #MetaCursorTracker object
- * @coords: (out caller-allocates): the coordinates of the pointer
- * @mods: (out): the current #ClutterModifierType of the pointer
+ * @coords: (out caller-allocates) (optional): the coordinates of the pointer
+ * @mods: (out) (optional): the current #ClutterModifierType of the pointer
  *
  * Get the current pointer position and state.
  */