Update docs

docs/reference/gdk/Makefile.am

@@ -134,7 +134,42 @@ HTML_IMAGES = 				\
 	images/umbrella.png		\
 	images/ur_angle.png		\
 	images/watch.png		\
-	images/xterm.png
+	images/xterm.png		\
+	images/alias_cursor.png		\
+	images/all_scroll_cursor.png	\
+	images/cell_cursor.png		\
+	images/col_resize_cursor.png	\
+	images/copy_cursor.png		\
+	images/crosshair_cursor.png	\
+	images/default_cursor.png	\
+	images/e_resize_cursor.png	\
+	images/ew_resize_cursor.png	\
+	images/grabbing_cursor.png	\
+	images/grab_cursor.png		\
+	images/hand_cursor.png		\
+	images/help_cursor.png		\
+	images/move_cursor.png		\
+	images/ne_resize_cursor.png	\
+	images/nesw_resize_cursor.png	\
+	images/no_drop_cursor.png	\
+	images/not_allowed_cursor.png	\
+	images/n_resize_cursor.png	\
+	images/ns_resize_cursor.png	\
+	images/nw_resize_cursor.png	\
+	images/nwse_resize_cursor.png	\
+	images/pointer_cursor.png	\
+	images/progress_cursor.png	\
+	images/row_resize_cursor.png	\
+	images/se_resize_cursor.png	\
+	images/s_resize_cursor.png	\
+	images/sw_resize_cursor.png	\
+	images/text_cursor.png		\
+	images/vertical_text_cursor.png	\
+	images/wait_cursor.png		\
+	images/w_resize_cursor.png	\
+	images/X_cursor.png		\
+	images/zoom_in_cursor.png	\
+	images/zoom_out_cursor.png
 
 if ENABLE_DOC_CROSS_REFERENCES
 # Extra options to supply to gtkdoc-fixref

gdk/gdkcursor.c

@@ -225,6 +225,7 @@ gdk_cursor_get_cursor_type (GdkCursor *cursor)
  * @cursor_type: cursor to create
  *
  * Creates a new cursor from the set of builtin cursors.
+ *
  * Some useful ones are:
  * - ![](right_ptr.png) #GDK_RIGHT_PTR (right-facing arrow)
  * - ![](crosshair.png) #GDK_CROSSHAIR (crosshair)
@@ -266,6 +267,44 @@ gdk_cursor_new_for_display (GdkDisplay    *display,
  * Creates a new cursor by looking up @name in the current cursor
  * theme.
  *
+ * A recommended set of cursor names that will work across different
+ * platforms can be found in the CSS specification:
+ * - "none"
+ * - ![](default_cursor.png) "default"
+ * - ![](help_cursor.png) "help"
+ * - ![](pointer_cursor.png) "pointer"
+ * - ![](progress_cursor.png) "progress"
+ * - ![](wait_cursor.png) "wait"
+ * - ![](cell_cursor.png) "cell"
+ * - ![](crosshair_cursor.png) "crosshair"
+ * - ![](text_cursor.png) "text"
+ * - ![](vertical_text_cursor.png) "vertical-text"
+ * - ![](alias_cursor.png) "alias"
+ * - ![](copy_cursor.png) "copy"
+ * - ![](move_cursor.png) "move"
+ * - ![](no_drop_cursor.png) "no-drop"
+ * - ![](not_allowed_cursor.png) "not-allowed"
+ * - ![](grab_cursor.png) "grab"
+ * - ![](grabbing_cursor.png) "grabbing"
+ * - ![](all_scroll_cursor.png) "all-scroll"
+ * - ![](col_resize_cursor.png) "col-resize"
+ * - ![](row_resize_cursor.png) "row-resize"
+ * - ![](n_resize_cursor.png) "n-resize"
+ * - ![](e_resize_cursor.png) "e-resize"
+ * - ![](s_resize_cursor.png) "s-resize"
+ * - ![](w_resize_cursor.png) "w-resize"
+ * - ![](ne_resize_cursor.png) "ne-resize"
+ * - ![](nw_resize_cursor.png) "nw-resize"
+ * - ![](sw_resize_cursor.png) "sw-resize"
+ * - ![](se_resize_cursor.png) "se-resize"
+ * - ![](ew_resize_cursor.png) "ew-resize"
+ * - ![](ns_resize_cursor.png) "ns-resize"
+ * - ![](nesw_resize_cursor.png) "nesw-resize"
+ * - ![](nwse_resize_cursor.png) "nwse-resize"
+ * - ![](zoom_in_cursor.png) "zoom-in"
+ * - ![](zoom_out_cursor.png) "zoom-out"
+ *
+ *
  * Returns: (nullable): a new #GdkCursor, or %NULL if there is no
  *   cursor with the given name
  *

gdk/gdkcursor.h

@@ -124,7 +124,12 @@ G_BEGIN_DECLS
  * @GDK_CURSOR_IS_PIXMAP: type of cursors constructed with
  *   gdk_cursor_new_from_pixbuf()
  *
- * The standard cursors available.
+ * Predefined cursors.
+ *
+ * Note that these IDs are directly taken from the X cursor font, and many
+ * of these cursors are either not useful, or are not available on other platforms.
+ *
+ * The recommended way to create cursors is to use gdk_cursor_new_from_name().
  */
 typedef enum
 {