docs: Add "Accessibility" section to various widgets

There are a few widgets that gained an accessible role, which means
adding an "Accessibility" section in their description.

11 files changed, 58 insertions, 22 deletions

diff --git a/gtk/gtkbox.c b/gtk/gtkbox.c
index 39aafdecd8..957678a3c0 100644
--- a/gtk/gtkbox.c
+++ b/gtk/gtkbox.c
@@ -51,6 +51,10 @@
  * # CSS nodes
  *
  * GtkBox uses a single CSS node with name box.
+ *
+ * # Accessibility
+ *
+ * GtkBox uses the %GTK_ACCESSIBLE_ROLE_GROUP role.
  */
 
 #include "config.h"
diff --git a/gtk/gtkcenterbox.c b/gtk/gtkcenterbox.c
index 097d135017..9ea5a241e0 100644
--- a/gtk/gtkcenterbox.c
+++ b/gtk/gtkcenterbox.c
@@ -50,6 +50,10 @@
  *
  * In vertical orientation, the nodes of the children are arranged from top to
  * bottom.
+ *
+ * # Accessibility
+ *
+ * GtkCenterBox uses the %GTK_ACCESSIBLE_ROLE_GROUP role.
  */
 
 #include "config.h"
diff --git a/gtk/gtkenums.h b/gtk/gtkenums.h
index 8f0f7edc98..206fdbef12 100644
--- a/gtk/gtkenums.h
+++ b/gtk/gtkenums.h
@@ -1136,7 +1136,8 @@ typedef enum {
  * @GTK_ACCESSIBLE_ROLE_GENERIC: Unused
  * @GTK_ACCESSIBLE_ROLE_GRID: A grid of items.
  * @GTK_ACCESSIBLE_ROLE_GRID_CELL: An item in a grid or tree grid.
- * @GTK_ACCESSIBLE_ROLE_GROUP: Unused
+ * @GTK_ACCESSIBLE_ROLE_GROUP: An element that groups multiple widgets. GTK uses
+ *   this role for various containers, like #GtkBox, #GtkViewport, and #GtkHeaderBar.
  * @GTK_ACCESSIBLE_ROLE_HEADING: Unused
  * @GTK_ACCESSIBLE_ROLE_IMG: An image.
  * @GTK_ACCESSIBLE_ROLE_INPUT: Abstract role.
diff --git a/gtk/gtkgrid.c b/gtk/gtkgrid.c
index 4c21f29806..4f8d35492e 100644
--- a/gtk/gtkgrid.c
+++ b/gtk/gtkgrid.c
@@ -50,7 +50,11 @@
  *
  * # CSS nodes
  *
- * GtkGrid uses a single CSS node with name grid.
+ * GtkGrid uses a single CSS node with name `grid`.
+ *
+ * # Accessibility
+ *
+ * GtkGrid uses the %GTK_ACCESSIBLE_ROLE_GROUP role.
  */
 
 typedef struct
diff --git a/gtk/gtkheaderbar.c b/gtk/gtkheaderbar.c
index 745d5ce672..9006bea9e0 100644
--- a/gtk/gtkheaderbar.c
+++ b/gtk/gtkheaderbar.c
@@ -96,13 +96,17 @@
  *             ╰── windowcontrols.end
  * ]|
  *
- * A #GtkHeaderBar's CSS node is called headerbar. It contains a windowhandle
- * subnode, which contains a box subnode, which contains two box subnodes at
- * the start and end of the headerbar, as well as a center node that represents
+ * A #GtkHeaderBar's CSS node is called `headerbar`. It contains a `windowhandle`
+ * subnode, which contains a `box` subnode, which contains two `box` subnodes at
+ * the start and end of the header bar, as well as a center node that represents
  * the title.
  *
- * Each of the boxes contains a windowcontrols subnode, see #GtkWindowControls
+ * Each of the boxes contains a `windowcontrols` subnode, see #GtkWindowControls
  * for details, as well as other children.
+ *
+ * # Accessibility
+ *
+ * GtkHeaderBar uses the %GTK_ACCESSIBLE_ROLE_GROUP role.
  */
 
 #define MIN_TITLE_CHARS 5
diff --git a/gtk/gtknotebook.c b/gtk/gtknotebook.c
index 945a13da6a..4daddb7b76 100644
--- a/gtk/gtknotebook.c
+++ b/gtk/gtknotebook.c
@@ -126,30 +126,33 @@
  *     ╰── <child>
  * ]|
  *
- * GtkNotebook has a main CSS node with name notebook, a subnode
- * with name header and below that a subnode with name tabs which
- * contains one subnode per tab with name tab.
+ * GtkNotebook has a main CSS node with name `notebook`, a subnode
+ * with name `header` and below that a subnode with name `tabs` which
+ * contains one subnode per tab with name `tab`.
  *
  * If action widgets are present, their CSS nodes are placed next
- * to the tabs node. If the notebook is scrollable, CSS nodes with
- * name arrow are placed as first and last child of the tabs node.
+ * to the `tabs` node. If the notebook is scrollable, CSS nodes with
+ * name `arrow` are placed as first and last child of the `tabs` node.
  *
- * The main node gets the .frame style class when the notebook
+ * The main node gets the `.frame` style class when the notebook
  * has a border (see gtk_notebook_set_show_border()).
  *
- * The header node gets one of the style class .top, .bottom,
- * .left or .right, depending on where the tabs are placed. For
- * reorderable pages, the tab node gets the .reorderable-page class.
+ * The header node gets one of the style class `.top`, `.bottom`,
+ * `.left` or `.right`, depending on where the tabs are placed. For
+ * reorderable pages, the tab node gets the `.reorderable-page` class.
  *
- * A tab node gets the .dnd style class while it is moved with drag-and-drop.
+ * A `tab` node gets the `.dnd` style class while it is moved with drag-and-drop.
  *
  * The nodes are always arranged from left-to-right, regardless of text direction.
  *
  * # Accessibility
  *
- * GtkNotebook uses the #GTK_ACCESSIBLE_ROLE_TAB_LIST and
- * #GTK_ACCESSIBLE_ROLE_TAB roles for its list of tabs and the
- * #GTK_ACCESSIBLE_ROLE_TAB_PANEL for the pages.
+ * GtkNotebook uses the following roles:
+ *
+ *  - %GTK_ACCESSIBLE_ROLE_GROUP for the notebook widget
+ *  - %GTK_ACCESSIBLE_ROLE_TAB_LIST for the list of tabs
+ *  - %GTK_ACCESSIBLE_ROLE_TAB role for each tab
+ *  - %GTK_ACCESSIBLE_ROLE_TAB_PANEL for each page
  */
 
 
diff --git a/gtk/gtkscrolledwindow.c b/gtk/gtkscrolledwindow.c
index 52a8ac77d4..09624cdc02 100644
--- a/gtk/gtkscrolledwindow.c
+++ b/gtk/gtkscrolledwindow.c
@@ -142,6 +142,10 @@
  *
  * If both scrollbars are visible, the area where they meet is drawn
  * with a subnode named junction.
+ *
+ * # Accessibility
+ *
+ * GtkScrolledWindow uses the %GTK_ACCESSIBLE_ROLE_GROUP role.
  */
 
 
diff --git a/gtk/gtkviewport.c b/gtk/gtkviewport.c
index 8fdef6123d..42bf850864 100644
--- a/gtk/gtkviewport.c
+++ b/gtk/gtkviewport.c
@@ -53,7 +53,11 @@
  *
  * # CSS nodes
  *
- * GtkViewport has a single CSS node with name viewport.
+ * GtkViewport has a single CSS node with name `viewport`.
+ *
+ * # Accessibility
+ *
+ * GtkViewport uses the %GTK_ACCESSIBLE_ROLE_GROUP role.
  */
 
 typedef struct _GtkViewportPrivate       GtkViewportPrivate;
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 68889591e7..085e54b788 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -142,7 +142,7 @@
  *
  * # Accessibility
  *
- * GtkWindow uses the #GTK_ACCESSIBLE_ROLE_WINDOW role.
+ * GtkWindow uses the %GTK_ACCESSIBLE_ROLE_WINDOW role.
  */
 
 #define MENU_BAR_ACCEL GDK_KEY_F10
diff --git a/gtk/gtkwindowcontrols.c b/gtk/gtkwindowcontrols.c
index 7278dfafff..553cbbdf0f 100644
--- a/gtk/gtkwindowcontrols.c
+++ b/gtk/gtkwindowcontrols.c
@@ -79,6 +79,10 @@
  * and #GtkWindowControls:decoration-layout value.
  *
  * When #GtkWindowControls:empty is %TRUE, it gets the .empty style class.
+ *
+ * # Accessibility
+ *
+ * GtkWindowHandle uses the %GTK_ACCESSIBLE_ROLE_GROUP role.
  */
 
 struct _GtkWindowControls {
diff --git a/gtk/gtkwindowhandle.c b/gtk/gtkwindowhandle.c
index fca0c3440d..5a6beeb273 100644
--- a/gtk/gtkwindowhandle.c
+++ b/gtk/gtkwindowhandle.c
@@ -48,7 +48,11 @@
  *
  * # CSS nodes
  *
- * #GtkWindowHandle has a single CSS node with the name windowhandle.
+ * #GtkWindowHandle has a single CSS node with the name `windowhandle`.
+ *
+ * # Accessibility
+ *
+ * GtkWindowHandle uses the %GTK_ACCESSIBLE_ROLE_GROUP role.
  */
 
 struct _GtkWindowHandle {