From 8cf622f0746c3d30774a9eace357eee1fb916db1 Mon Sep 17 00:00:00 2001
From: Drew DeVault <sir@cmpwn.com>
Date: Thu, 1 Feb 2018 20:30:18 -0500
Subject: [PATCH] Improve xcursor docs

---
 include/wlr/types/wlr_xcursor_manager.h | 30 ++++++++++++++++---------
 include/wlr/xcursor.h                   | 17 ++++++++++++++
 2 files changed, 36 insertions(+), 11 deletions(-)

diff --git a/include/wlr/types/wlr_xcursor_manager.h b/include/wlr/types/wlr_xcursor_manager.h
index 2a2c9035..c7fa83be 100644
--- a/include/wlr/types/wlr_xcursor_manager.h
+++ b/include/wlr/types/wlr_xcursor_manager.h
@@ -6,7 +6,7 @@
 #include <wlr/xcursor.h>
 
 /**
- * A scaled XCursor theme.
+ * An XCursor theme at a particular scale factor of the base size.
  */
 struct wlr_xcursor_manager_theme {
 	float scale;
@@ -15,11 +15,10 @@ struct wlr_xcursor_manager_theme {
 };
 
 /**
- * Manage multiple XCursor themes with different scales and set `wlr_cursor`
- * images.
- *
- * This manager can be used to display cursor images on multiple outputs having
- * different scale factors.
+ * wlr_xcursor_manager dynamically loads xcursor themes at sizes necessary for
+ * use on outputs at arbitrary scale factors. You should call
+ * wlr_xcursor_manager_load for each output you will show your cursor on, with
+ * the scale factor parameter set to that output's scale factor.
  */
 struct wlr_xcursor_manager {
 	char *name;
@@ -28,24 +27,33 @@ struct wlr_xcursor_manager {
 };
 
 /**
- * Create a new XCursor manager. After initialization, scaled themes need to be
- * loaded with `wlr_xcursor_manager_load`. `size` is the unscaled cursor theme
- * size.
+ * Creates a new XCursor manager with the given xcursor theme name and base size
+ * (for use when scale=1).
  */
 struct wlr_xcursor_manager *wlr_xcursor_manager_create(const char *name,
 	uint32_t size);
 
 void wlr_xcursor_manager_destroy(struct wlr_xcursor_manager *manager);
 
+/**
+ * Ensures an xcursor theme at the given scale factor is loaded in the manager.
+ */
 int wlr_xcursor_manager_load(struct wlr_xcursor_manager *manager,
 	float scale);
 
+/**
+ * Retrieves a wlr_xcursor reference for the given cursor name at the given
+ * scale factor, or NULL if this wlr_xcursor_manager has not loaded a cursor
+ * theme at the requested scale.
+ */
 struct wlr_xcursor *wlr_xcursor_manager_get_xcursor(
 	struct wlr_xcursor_manager *manager, const char *name, float scale);
 
 /**
- * Set a `wlr_cursor` image. The manager uses all currently loaded scaled
- * themes.
+ * Set a wlr_cursor's cursor image to the specified cursor name for all scale
+ * factors. wlr_cursor will take over from this point and ensure the correct
+ * cursor is used on each output, assuming a wlr_output_layout is attached to
+ * it.
  */
 void wlr_xcursor_manager_set_cursor_image(struct wlr_xcursor_manager *manager,
 	const char *name, struct wlr_cursor *cursor);
diff --git a/include/wlr/xcursor.h b/include/wlr/xcursor.h
index 42fcedb9..c7c89e02 100644
--- a/include/wlr/xcursor.h
+++ b/include/wlr/xcursor.h
@@ -50,6 +50,9 @@ struct wlr_xcursor {
 	uint32_t total_delay; /* length of the animation in ms */
 };
 
+/**
+ * Contanier for an Xcursor theme.
+ */
 struct wlr_xcursor_theme {
 	unsigned int cursor_count;
 	struct wlr_xcursor **cursors;
@@ -57,13 +60,27 @@ struct wlr_xcursor_theme {
 	int size;
 };
 
+/**
+ * Loads the named xcursor theme at the given cursor size (in pixels). This is
+ * useful if you need cursor images for your compositor to use when a
+ * client-side cursors is not available or you wish to override client-side
+ * cursors for a particular UI interaction (such as using a grab cursor when
+ * moving a window around).
+ */
 struct wlr_xcursor_theme *wlr_xcursor_theme_load(const char *name, int size);
 
 void wlr_xcursor_theme_destroy(struct wlr_xcursor_theme *theme);
 
+/**
+ * Obtains a wlr_xcursor image for the specified cursor name (e.g. "left_ptr").
+ */
 struct wlr_xcursor *wlr_xcursor_theme_get_cursor(
 	struct wlr_xcursor_theme *theme, const char *name);
 
+/**
+ * Returns the current frame number for an animated cursor give a monotonic time
+ * reference.
+ */
 int wlr_xcursor_frame(struct wlr_xcursor *cursor, uint32_t time);
 
 /**