a11y: Document roles of widgets

Add a section to the long description for each
widget that is using a non-default accessible role.

10 files changed, 87 insertions, 47 deletions

diff --git a/gtk/gtkbutton.c b/gtk/gtkbutton.c
index 173d4e8bf1..d85d65ca48 100644
--- a/gtk/gtkbutton.c
+++ b/gtk/gtkbutton.c
@@ -49,6 +49,10 @@
  * #GtkLockButton, #GtkColorButton or #GtkFontButton use style classes such as
  * .toggle, .popup, .scale, .lock, .color on the button node
  * to differentiate themselves from a plain GtkButton.
+ *
+ * # Accessibility
+ *
+ * GtkButton uses the #GTK_ACCESSIBLE_ROLE_BUTTON role.
  */
 
 #include "config.h"
diff --git a/gtk/gtkcheckbutton.c b/gtk/gtkcheckbutton.c
index 82e2fd5963..802355d9d4 100644
--- a/gtk/gtkcheckbutton.c
+++ b/gtk/gtkcheckbutton.c
@@ -73,6 +73,10 @@
  * A GtkCheckButton without indicator changes the name of its main node
  * to button and adds a .check style class to it. The subnode is invisible
  * in this case.
+ *
+ * # Accessibility
+ *
+ * GtkCheckButton uses the #GTK_ACCESSIBLE_ROLE_CHECKBOX role.
  */
 
 typedef struct {
diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c
index 40a5e159b0..9c1f05436e 100644
--- a/gtk/gtkdialog.c
+++ b/gtk/gtkdialog.c
@@ -157,6 +157,10 @@
  *   </action-widgets>
  * </object>
  * ]|
+ *
+ * # Accessibility
+ *
+ * GtkDialog uses the #GTK_ACCESSIBLE_ROLE_DIALOG role.
  */
 
 typedef struct _ResponseData ResponseData;
diff --git a/gtk/gtkprogressbar.c b/gtk/gtkprogressbar.c
index 1041e1185f..6255296ea9 100644
--- a/gtk/gtkprogressbar.c
+++ b/gtk/gtkprogressbar.c
@@ -85,6 +85,10 @@
  * .right, .top or .bottom added when the progress 'touches' the corresponding
  * end of the GtkProgressBar. The .osd class on the progressbar node is for use
  * in overlays like the one Epiphany has for page loading progress.
+ *
+ * # Accessibility
+ *
+ * GtkProgressBar uses the #GTK_ACCESSIBLE_ROLE_PROGRESS_BAR role.
  */
 
 typedef struct _GtkProgressBarClass         GtkProgressBarClass;
diff --git a/gtk/gtkradiobutton.c b/gtk/gtkradiobutton.c
index 5a73b8ce36..a986f3cc89 100644
--- a/gtk/gtkradiobutton.c
+++ b/gtk/gtkradiobutton.c
@@ -69,27 +69,6 @@
  * The group list does not need to be freed, as each #GtkRadioButton will remove
  * itself and its list item when it is destroyed.
  *
- * # CSS nodes
- *
- * |[<!-- language="plain" -->
- * radiobutton
- * ├── radio
- * ╰── <child>
- * ]|
- *
- * A GtkRadioButton with indicator (see gtk_check_button_set_draw_indicator())) has a
- * main CSS node with name radiobutton and a subnode with name radio.
- *
- * |[<!-- language="plain" -->
- * button.radio
- * ├── radio
- * ╰── <child>
- * ]|
- *
- * A GtkRadioButton without indicator changes the name of its main node
- * to button and adds a .radio style class to it. The subnode is invisible
- * in this case.
- *
  * ## How to create a group of two radio buttons.
  *
  * |[<!-- language="C" -->
@@ -124,6 +103,31 @@
  * selected button.
  * Inside the #GtkToggleButton::toggled handler, gtk_toggle_button_get_active()
  * can be used to determine if the button has been selected or deselected.
+ *
+ * # CSS nodes
+ *
+ * |[<!-- language="plain" -->
+ * radiobutton
+ * ├── radio
+ * ╰── <child>
+ * ]|
+ *
+ * A GtkRadioButton with indicator (see gtk_check_button_set_draw_indicator())) has a
+ * main CSS node with name radiobutton and a subnode with name radio.
+ *
+ * |[<!-- language="plain" -->
+ * button.radio
+ * ├── radio
+ * ╰── <child>
+ * ]|
+ *
+ * A GtkRadioButton without indicator changes the name of its main node
+ * to button and adds a .radio style class to it. The subnode is invisible
+ * in this case.
+ *
+ * # Accessibility
+ *
+ * GtkRadioButton uses the #GTK_ACCESSIBLE_ROLE_RADIO role.
  */
 
 typedef struct _GtkRadioButtonClass         GtkRadioButtonClass;
diff --git a/gtk/gtkscale.c b/gtk/gtkscale.c
index ed8316ade6..4317ac2baa 100644
--- a/gtk/gtkscale.c
+++ b/gtk/gtkscale.c
@@ -125,6 +125,10 @@
  * If the scale is displaying the value (see #GtkScale:draw-value), there is
  * subnode with name value. This node will get the .top or .bottom style classes
  * similar to the marks node.
+ *
+ * # Accessibility
+ *
+ * GtkScale uses the #GTK_ACCESSIBLE_ROLE_SLIDER role.
  */
 
 
diff --git a/gtk/gtkscrollbar.c b/gtk/gtkscrollbar.c
index 25dd7ff9cb..ceae0caae8 100644
--- a/gtk/gtkscrollbar.c
+++ b/gtk/gtkscrollbar.c
@@ -78,6 +78,10 @@
  * Other style classes that may be added to scrollbars inside #GtkScrolledWindow
  * include the positional classes (.left, .right, .top, .bottom) and style
  * classes related to overlay scrolling (.overlay-indicator, .dragging, .hovering).
+ *
+ * # Accessibility
+ *
+ * GtkScrollbar uses the #GTK_ACCESSIBLE_ROLE_SCROLLBAR role.
  */
 
 typedef struct _GtkScrollbarClass   GtkScrollbarClass;
diff --git a/gtk/gtkseparator.c b/gtk/gtkseparator.c
index 63ad838027..fe9ac58437 100644
--- a/gtk/gtkseparator.c
+++ b/gtk/gtkseparator.c
@@ -46,6 +46,10 @@
  *
  * GtkSeparator has a single CSS node with name separator. The node
  * gets one of the .horizontal or .vertical style classes.
+ *
+ * # Accessibility
+ *
+ * GtkSeparator uses the #GTK_ACCESSIBLE_ROLE_SEPARATOR role.
  */
 
 typedef struct _GtkSeparatorClass GtkSeparatorClass;
diff --git a/gtk/gtkspinbutton.c b/gtk/gtkspinbutton.c
index f008fac004..d6517459cb 100644
--- a/gtk/gtkspinbutton.c
+++ b/gtk/gtkspinbutton.c
@@ -90,32 +90,6 @@
  * not desired, the automatic sizing can be turned off by explicitly
  * setting #GtkSpinButton::width-chars to a value != -1.
  *
- * # CSS nodes
- *
- * |[<!-- language="plain" -->
- * spinbutton.horizontal
- * ├── text
- * │    ├── undershoot.left
- * │    ╰── undershoot.right
- * ├── button.down
- * ╰── button.up
- * ]|
- *
- * |[<!-- language="plain" -->
- * spinbutton.vertical
- * ├── button.up
- * ├── text
- * │    ├── undershoot.left
- * │    ╰── undershoot.right
- * ╰── button.down
- * ]|
- *
- * GtkSpinButtons main CSS node has the name spinbutton. It creates subnodes
- * for the entry and the two buttons, with these names. The button nodes have
- * the style classes .up and .down. The GtkText subnodes (if present) are put
- * below the text node. The orientation of the spin button is reflected in
- * the .vertical or .horizontal style class on the main node.
- *
  * ## Using a GtkSpinButton to get an integer
  *
  * |[<!-- language="C" -->
@@ -178,6 +152,36 @@
  *   gtk_widget_show (window);
  * }
  * ]|
+ *
+ * # CSS nodes
+ *
+ * |[<!-- language="plain" -->
+ * spinbutton.horizontal
+ * ├── text
+ * │    ├── undershoot.left
+ * │    ╰── undershoot.right
+ * ├── button.down
+ * ╰── button.up
+ * ]|
+ *
+ * |[<!-- language="plain" -->
+ * spinbutton.vertical
+ * ├── button.up
+ * ├── text
+ * │    ├── undershoot.left
+ * │    ╰── undershoot.right
+ * ╰── button.down
+ * ]|
+ *
+ * GtkSpinButtons main CSS node has the name spinbutton. It creates subnodes
+ * for the entry and the two buttons, with these names. The button nodes have
+ * the style classes .up and .down. The GtkText subnodes (if present) are put
+ * below the text node. The orientation of the spin button is reflected in
+ * the .vertical or .horizontal style class on the main node.
+ *
+ * # Accessiblity
+ *
+ * GtkSpinButton uses the #GTK_ACCESSIBLE_ROLE_SPIN_BUTTON role.
  */
 
 typedef struct _GtkSpinButton      GtkSpinButton;
diff --git a/gtk/gtkswitch.c b/gtk/gtkswitch.c
index 9e4aff1bcb..f4cc9f3615 100644
--- a/gtk/gtkswitch.c
+++ b/gtk/gtkswitch.c
@@ -47,6 +47,10 @@
  *
  * GtkSwitch has four css nodes, the main node with the name switch and subnodes
  * for the slider and the on and off labels. Neither of them is using any style classes.
+ *
+ * # Accessibility
+ *
+ * GtkSwitch uses the #GTK_ACCESSIBLE_ROLE_SWITCH role.
  */
 
 #include "config.h"