[gtk/ebassi/for-master] docs: Add example of relations with lists of references

[Emmanuele Bassi <ebassi src gnome org>]

commit 2229d7f66c91fb44f828af1325e7b0233b34ba37
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Tue Nov 10 14:38:09 2020 +0000

    docs: Add example of relations with lists of references

 docs/reference/gtk/section-accessibility.md | 16 ++++++++++------
 gtk/gtkaccessible.c                         | 12 ++++++++++++
 2 files changed, 22 insertions(+), 6 deletions(-)
---
diff --git a/docs/reference/gtk/section-accessibility.md b/docs/reference/gtk/section-accessibility.md
index b86aac419b..b8145e0ad3 100644
--- a/docs/reference/gtk/section-accessibility.md
+++ b/docs/reference/gtk/section-accessibility.md
@@ -165,13 +165,13 @@ Each relation name is part of the #GtkAccessibleRelation enumeration.
 | %GTK_ACCESSIBLE_RELATION_COL_INDEX | “aria-colindex” | integer |
 | %GTK_ACCESSIBLE_RELATION_COL_INDEX_TEXT | “aria-colindextext” | translatable string |
 | %GTK_ACCESSIBLE_RELATION_COL_SPAN | “aria-colspan” | integer |
-| %GTK_ACCESSIBLE_RELATION_CONTROLS | “aria-controls” | a #GList of #GtkAccessible |
-| %GTK_ACCESSIBLE_RELATION_DESCRIBED_BY | “aria-describedby” | a #GList of #GtkAccessible |
-| %GTK_ACCESSIBLE_RELATION_DETAILS | “aria-details” | a #GList of #GtkAccessible |
+| %GTK_ACCESSIBLE_RELATION_CONTROLS | “aria-controls” | a list of #GtkAccessible |
+| %GTK_ACCESSIBLE_RELATION_DESCRIBED_BY | “aria-describedby” | a list of #GtkAccessible |
+| %GTK_ACCESSIBLE_RELATION_DETAILS | “aria-details” | a list of #GtkAccessible |
 | %GTK_ACCESSIBLE_RELATION_ERROR_MESSAGE | “aria-errormessage” | #GtkAccessible |
-| %GTK_ACCESSIBLE_RELATION_FLOW_TO | “aria-flowto” | a #GList of #GtkAccessible |
-| %GTK_ACCESSIBLE_RELATION_LABELLED_BY | “aria-labelledby” | a #GList of #GtkAccessible |
-| %GTK_ACCESSIBLE_RELATION_OWNS | “aria-owns” | a #GList of #GtkAccessible |
+| %GTK_ACCESSIBLE_RELATION_FLOW_TO | “aria-flowto” | a list of #GtkAccessible |
+| %GTK_ACCESSIBLE_RELATION_LABELLED_BY | “aria-labelledby” | a list of #GtkAccessible |
+| %GTK_ACCESSIBLE_RELATION_OWNS | “aria-owns” | a list of #GtkAccessible |
 | %GTK_ACCESSIBLE_RELATION_POS_IN_SET | “aria-posinset” | integer |
 | %GTK_ACCESSIBLE_RELATION_ROW_COUNT | “aria-rowcount” | integer |
 | %GTK_ACCESSIBLE_RELATION_ROW_INDEX | “aria-rowindex” | integer |
@@ -179,6 +179,10 @@ Each relation name is part of the #GtkAccessibleRelation enumeration.
 | %GTK_ACCESSIBLE_RELATION_ROW_SPAN | “aria-rowspan” | integer |
 | %GTK_ACCESSIBLE_RELATION_SET_SIZE | “aria-setsize” | integer |
 
+*Note*: When using gtk_accessible_update_relation() with a relation that
+requires a list of #GtkAccessible instances, you should pass every
+accessible object separately, followed by %NULL. 
+
 ## Application development rules
 
 Even if standard UI controls provided by GTK have accessibility information
diff --git a/gtk/gtkaccessible.c b/gtk/gtkaccessible.c
index 39c31d5b1e..13c4cb35ed 100644
--- a/gtk/gtkaccessible.c
+++ b/gtk/gtkaccessible.c
@@ -411,6 +411,18 @@ gtk_accessible_reset_property (GtkAccessible         *self,
  *
  * This function should be called by #GtkWidget types whenever an accessible
  * relation change must be communicated to assistive technologies.
+ *
+ * If the #GtkAccessibleRelation requires a list of references, you should
+ * pass each reference individually, followed by %NULL, e.g.
+ *
+ * |[<!-- language="C" -->
+ *   gtk_accessible_update_relation (accessible,
+ *                                   GTK_ACCESSIBLE_RELATION_CONTROLS,
+ *                                     ref1, NULL,
+ *                                   GTK_ACCESSIBLE_LABELLED_BY,
+ *                                     ref1, ref2, ref3, NULL,
+ *                                   -1);
+ * ]|
  */
 void
 gtk_accessible_update_relation (GtkAccessible         *self,