Merge branch 'enums-docs' into 'main'

docs: Improve docs for enums

See merge request GNOME/gtk!6609

gdk/gdkevents.h

@@ -165,12 +165,18 @@ typedef struct _GdkTouchpadEvent        GdkTouchpadEvent;
  * @GDK_PAD_RING: A tablet pad axis event from a "ring".
  * @GDK_PAD_STRIP: A tablet pad axis event from a "strip".
  * @GDK_PAD_GROUP_MODE: A tablet pad group mode change.
- * @GDK_TOUCHPAD_HOLD: A touchpad hold gesture event, the current state
- *   is determined by its phase field. Since: 4.6
  * @GDK_EVENT_LAST: marks the end of the GdkEventType enumeration.
  *
  * Specifies the type of the event.
  */
+/**
+  * GDK_TOUCHPAD_HOLD:
+  *
+  * A touchpad hold gesture event, the current state is determined by its phase
+  * field.
+  *
+  * Since: 4.6
+  */
 typedef enum
 {
   GDK_DELETE,

gsk/gskenums.h

@@ -49,14 +49,50 @@
  * @GSK_BLUR_NODE: A node that applies a blur
  * @GSK_DEBUG_NODE: Debug information that does not affect the rendering
  * @GSK_GL_SHADER_NODE: A node that uses OpenGL fragment shaders to render
- * @GSK_TEXTURE_SCALE_NODE: A node drawing a `GdkTexture` scaled and filtered. Since: 4.10
- * @GSK_MASK_NODE: A node that masks one child with another. Since: 4.10
- * @GSK_FILL_NODE: A node that fills a path. Since: 4.14
- * @GSK_STROKE_NODE: A node that strokes a path. Since: 4.14
- * @GSK_SUBSURFACE_NODE: A node possibly redirects part of the scene graph to a subsurface. Since: 4.14
  *
  * The type of a node determines what the node is rendering.
  */
+
+/**
+ * GSK_TEXTURE_SCALE_NODE:
+ *
+ * A node drawing a `GdkTexture` scaled and filtered.
+ *
+ * Since: 4.10
+ */
+
+/**
+ * GSK_MASK_NODE:
+ *
+ * A node that masks one child with another.
+ *
+ * Since: 4.10
+ */
+
+/**
+ * GSK_STROKE_NODE:
+ *
+ * A node that strokes a path.
+ *
+ * Since: 4.14
+ */
+
+/**
+ * GSK_FILL_NODE:
+ *
+ * A node that fills a path.
+ *
+ * Since: 4.14
+ */
+
+/**
+ * GSK_SUBSURFACE_NODE:
+ *
+ * A node that possibly redirects part of the scene graph to a subsurface.
+ *
+ * Since: 4.14
+ */
+
 typedef enum {
   GSK_NOT_A_RENDER_NODE = 0,
   GSK_CONTAINER_NODE,

gtk/gtkdebug.h

@@ -52,8 +52,6 @@ G_BEGIN_DECLS
  * @GTK_DEBUG_CONSTRAINTS: Information from the constraints solver
  * @GTK_DEBUG_BUILDER_OBJECTS: Log unused GtkBuilder objects
  * @GTK_DEBUG_A11Y: Information about accessibility state changes
- * @GTK_DEBUG_ICONFALLBACK: Information about icon fallback. Since: 4.2
- * @GTK_DEBUG_INVERT_TEXT_DIR: Inverts the default text-direction. Since: 4.8
  *
  * Flags to use with gtk_set_debug_flags().
  *
@@ -61,6 +59,23 @@ G_BEGIN_DECLS
  * types of debugging information. Some of these flags are
  * only available when GTK has been configured with `-Ddebug=true`.
  */
+
+/**
+ * GTK_DEBUG_ICONFALLBACK:
+ *
+ * Information about icon fallback.
+ *
+ * Since: 4.2
+ */
+
+/**
+ * GTK_DEBUG_INVERT_TEXT_DIR:
+ *
+ * Inverts the default text-direction.
+ *
+ * Since: 4.8
+ */
+
 typedef enum {
   GTK_DEBUG_TEXT            = 1 <<  0,
   GTK_DEBUG_TREE            = 1 <<  1,

gtk/gtkenums.h

@@ -41,10 +41,6 @@ G_BEGIN_DECLS
  * @GTK_ALIGN_START: snap to left or top side, leaving space on right or bottom
  * @GTK_ALIGN_END: snap to right or bottom side, leaving space on left or top
  * @GTK_ALIGN_CENTER: center natural width of widget inside the allocation
- * @GTK_ALIGN_BASELINE: align the widget according to the baseline.
- *   See [class@Gtk.Widget]. Deprecated: 4.12: Use `GTK_ALIGN_BASELINE_FILL` instead
- * @GTK_ALIGN_BASELINE_FILL: a different name for `GTK_ALIGN_BASELINE`. Since 4.12
- * @GTK_ALIGN_BASELINE_CENTER: stretch to fill all space, but align the baseline. Since 4.12
  *
  * Controls how a widget deals with extra space in a single dimension.
  *
@@ -63,6 +59,27 @@ G_BEGIN_DECLS
  * are treated similar to `GTK_ALIGN_CENTER` and `GTK_ALIGN_FILL`, except that it
  * positions the widget to line up the baselines, where that is supported.
  */
+/**
+ * GTK_ALIGN_BASELINE:
+ *
+ * align the widget according to the baseline.
+ *
+ * Deprecated: 4.12: Use `GTK_ALIGN_BASELINE_FILL` instead
+ */
+/**
+ * GTK_ALIGN_BASELINE_FILL:
+ *
+ * a different name for `GTK_ALIGN_BASELINE`.
+ *
+ * Since: 4.12
+ */
+/**
+ * GTK_ALIGN_BASELINE_CENTER:
+ *
+ * stretch to fill all space, but align the baseline.
+ *
+ * Since: 4.12
+ */
 typedef enum
 {
   GTK_ALIGN_FILL,
@@ -1356,29 +1373,65 @@ typedef enum {
  * @GTK_ACCESSIBLE_ROLE_WIDGET: Abstract role for interactive components of a
  *   graphical user interface
  * @GTK_ACCESSIBLE_ROLE_WINDOW: Abstract role for windows.
- * @GTK_ACCESSIBLE_ROLE_TOGGLE_BUTTON: A type of push button
- *   which stays pressed until depressed by a second activation.
- *   Since: 4.10
- * @GTK_ACCESSIBLE_ROLE_APPLICATION: A toplevel element of a graphical user interface.
- *   This is the role that GTK uses by default for windows.
- *   Since: 4.12
- * @GTK_ACCESSIBLE_ROLE_PARAGRAPH: A paragraph of content.
- *   Since: 4.14
- * @GTK_ACCESSIBLE_ROLE_BLOCK_QUOTE: A section of content that is quoted
- *   from another source.
- *   Since: 4.14
- * @GTK_ACCESSIBLE_ROLE_ARTICLE: A section of a page that consists of a
- *   composition that forms an independent part of a document, page, or site.
- *   Since: 4.14
- * @GTK_ACCESSIBLE_ROLE_COMMENT: A comment contains content expressing reaction
- *   to other content.
- *   Since: 4.14
  *
  * The accessible role for a [iface@Accessible] implementation.
  *
  * Abstract roles are only used as part of the ontology; application
  * developers must not use abstract roles in their code.
  */
+
+/**
+ * GTK_ACCESSIBLE_ROLE_TOGGLE_BUTTON:
+ *
+ * A type of push button which stays pressed until depressed by a second
+ * activation.
+ *
+ * Since: 4.10
+ */
+
+/**
+ * GTK_ACCESSIBLE_ROLE_APPLICATION:
+ *
+ * A toplevel element of a graphical user interface.
+ *
+ * This is the role that GTK uses by default for windows.
+ *
+ * Since: 4.12
+ */
+
+/**
+ * GTK_ACCESSIBLE_ROLE_PARAGRAPH:
+ *
+ * A paragraph of content.
+ *
+ * Since: 4.14
+ */
+
+/**
+ * GTK_ACCESSIBLE_ROLE_BLOCK_QUOTE:
+ *
+ * A section of content that is quoted from another source.
+ *
+ * Since: 4.14
+ */
+
+/**
+ * GTK_ACCESSIBLE_ROLE_ARTICLE:
+ *
+ * A section of a page that consists of a composition that forms an independent
+ * part of a document, page, or site.
+ *
+ * Since: 4.14
+ */
+
+/**
+ * GTK_ACCESSIBLE_ROLE_COMMENT:
+ *
+ * A comment contains content expressing reaction to other content.
+ *
+ * Since: 4.14
+ */
+
 typedef enum {
   GTK_ACCESSIBLE_ROLE_ALERT,
   GTK_ACCESSIBLE_ROLE_ALERT_DIALOG,
@@ -1489,12 +1542,17 @@ typedef enum {
  *   enumeration
  * @GTK_ACCESSIBLE_STATE_SELECTED: A “selected” state; set when a widget
  *   is selected. Value type: boolean or undefined
- * @GTK_ACCESSIBLE_STATE_VISITED: Indicates that a widget with the
- *   GTK_ACCESSIBLE_ROLE_LINK has been visited. Value type: boolean.
- *   Since: 4.12
  *
  * The possible accessible states of a [iface@Accessible].
  */
+/**
+  * GTK_ACCESSIBLE_STATE_VISITED:
+  *
+  * Indicates that a widget with the GTK_ACCESSIBLE_ROLE_LINK has been visited.
+  * Value type: boolean.
+  *
+  * Since: 4.12
+  */
 typedef enum {
   GTK_ACCESSIBLE_STATE_BUSY,
   GTK_ACCESSIBLE_STATE_CHECKED,