Merge branch 'docs-escape-xml-tag' into 'main'

Escape GtkBuilder XML tag in comment with backtick

Closes #5312

See merge request GNOME/gtk!5429

gtk/css/gtkcssparser.c

@@ -962,7 +962,7 @@ gtk_css_parser_parse_url_arg (GtkCssParser *parser,
  * gtk_css_parser_consume_url:
  * @self: a `GtkCssParser`
  *
- * If the parser matches the <url> token from the [CSS
+ * If the parser matches the `<url>` token from the [CSS
  * specification](https://drafts.csswg.org/css-values-4/#url-value),
  * consumes it, resolves the URL and returns the resulting `GFile`.
  * On failure, an error is emitted and %NULL is returned.

gtk/deprecated/gtkcomboboxtext.c

@@ -59,8 +59,8 @@ G_GNUC_BEGIN_IGNORE_DEPRECATIONS
  * ## GtkComboBoxText as GtkBuildable
  *
  * The `GtkComboBoxText` implementation of the `GtkBuildable` interface supports
- * adding items directly using the <items> element and specifying <item>
- * elements for each item. Each <item> element can specify the “id”
+ * adding items directly using the `<items>` element and specifying `<item>`
+ * elements for each item. Each `<item>` element can specify the “id”
  * corresponding to the appended text and also supports the regular
  * translation attributes “translatable”, “context” and “comments”.
  *

gtk/deprecated/gtktreestore.c

@@ -47,8 +47,8 @@ G_GNUC_BEGIN_IGNORE_DEPRECATIONS
  * ## GtkTreeStore as GtkBuildable
  *
  * The GtkTreeStore implementation of the `GtkBuildable` interface allows
- * to specify the model columns with a <columns> element that may contain
- * multiple <column> elements, each specifying one model column. The “type”
+ * to specify the model columns with a `<columns>` element that may contain
+ * multiple `<column>` elements, each specifying one model column. The “type”
  * attribute specifies the data type for the column.
  *
  * An example of a UI Definition fragment for a tree store:

gtk/gtkbuildable.c

@@ -80,7 +80,7 @@ gtk_buildable_set_buildable_id (GtkBuildable *buildable,
  * Gets the ID of the @buildable object.
  *
  * `GtkBuilder` sets the name based on the ID attribute
- * of the <object> tag used to construct the @buildable.
+ * of the `<object>` tag used to construct the @buildable.
  *
  * Returns: (nullable): the ID of the buildable object
  **/
@@ -193,7 +193,7 @@ gtk_buildable_construct_child (GtkBuildable *buildable,
  * @data: (out): return location for user data that will be passed in
  *   to parser functions
  *
- * This is called for each unknown element under <child>.
+ * This is called for each unknown element under `<child>`.
  *
  * Returns: %TRUE if an object has a custom implementation, %FALSE
  *   if it doesn't.

gtk/gtkbuildable.h

@@ -109,14 +109,14 @@ struct _GtkBuildableParser
  *  interface is created.
  * @construct_child: Constructs a child of a buildable that has been
  *  specified as “constructor” in the UI definition. This can be used to
- *  reference a widget created in a <ui> tag which is outside
+ *  reference a widget created in a `<ui>` tag which is outside
  *  of the normal GtkBuilder UI definition hierarchy.  A reference to the
  *  constructed object is returned and becomes owned by the caller.
  * @custom_tag_start: Implement this if the buildable needs to parse
- *  content below <child>. To handle an element, the implementation
+ *  content below `<child>`. To handle an element, the implementation
  *  must fill in the @parser and @user_data and return %TRUE.
  *  `GtkWidget` implements this to parse accessible attributes specified
- *  in <accessibility> elements.
+ *  in `<accessibility>` elements.
  *  Note that @user_data must be freed in @custom_tag_end or @custom_finished.
  * @custom_tag_end: Called for the end tag of each custom element that is
  *  handled by the buildable (see @custom_tag_start).

gtk/gtkbuilder.c

@@ -192,9 +192,9 @@
  *
  * Beyond this general structure, several object classes define their
  * own XML DTD fragments for filling in the ANY placeholders in the DTD
- * above. Note that a custom element in a <child> element gets parsed by
+ * above. Note that a custom element in a `<child>` element gets parsed by
  * the custom tag handler of the parent object, while a custom element in
- * an <object> element gets parsed by the custom tag handler of the object.
+ * an `<object>` element gets parsed by the custom tag handler of the object.
  *
  * These XML fragments are explained in the documentation of the
  * respective objects.

gtk/gtkbuilderscope.h

@@ -57,7 +57,7 @@ typedef enum { /*< prefix=GTK_BUILDER_CLOSURE >*/
  *   correct function name for registering the type and then use dlsym() to load it.
  *   The default implementation just tries g_type_from_name() and otherwise fails.
  * @get_type_from_function: Try to lookup a `GType` via the given function name, specified
- *   explicitly in a GtkBuilder file, like via the "type-func" attribute in the "<object>" tag.
+ *   explicitly in a GtkBuilder file, like via the "type-func" attribute in the `<object>` tag.
  *   This function is very rarely used.
  *   The C implementation will use dlsym() and call the resulting function as a `GTypeFunc`.
  *   The default implementation will fail and just return %G_TYPE_INVALID.

gtk/gtkcenterbox.c

@@ -37,7 +37,7 @@
  *
  * The `GtkCenterBox` implementation of the `GtkBuildable` interface
  * supports placing children in the 3 positions by specifying “start”, “center”
- * or “end” as the “type” attribute of a <child> element.
+ * or “end” as the “type” attribute of a `<child>` element.
  *
  * # CSS nodes
  *

gtk/gtkentry.c

@@ -135,8 +135,8 @@
  * # GtkEntry as GtkBuildable
  *
  * The `GtkEntry` implementation of the `GtkBuildable` interface supports a
- * custom <attributes> element, which supports any number of <attribute>
- * elements. The <attribute> element has attributes named “name“, “value“,
+ * custom `<attributes>` element, which supports any number of `<attribute>`
+ * elements. The `<attribute>` element has attributes named “name“, “value“,
  * “start“ and “end“ and allows you to specify `PangoAttribute` values for
  * this label.
  *

gtk/gtkexpander.c

@@ -79,8 +79,8 @@
  *
  * The `GtkExpander` implementation of the `GtkBuildable` interface supports
  * placing a child in the label position by specifying “label” as the
- * “type” attribute of a <child> element. A normal content child can be
- * specified without specifying a <child> type attribute.
+ * “type” attribute of a `<child>` element. A normal content child can be
+ * specified without specifying a `<child>` type attribute.
  *
  * An example of a UI definition fragment with GtkExpander:
  *

gtk/gtkframe.c

@@ -51,8 +51,8 @@
  *
  * The `GtkFrame` implementation of the `GtkBuildable` interface supports
  * placing a child in the label position by specifying “label” as the
- * “type” attribute of a <child> element. A normal content child can
- * be specified without specifying a <child> type attribute.
+ * “type” attribute of a `<child>` element. A normal content child can
+ * be specified without specifying a `<child>` type attribute.
  *
  * An example of a UI definition fragment with GtkFrame:
  * ```xml

gtk/gtkheaderbar.c

@@ -61,7 +61,7 @@
  *
  * The `GtkHeaderBar` implementation of the `GtkBuildable` interface supports
  * adding children at the start or end sides by specifying “start” or “end” as
- * the “type” attribute of a <child> element, or setting the title widget by
+ * the “type” attribute of a `<child>` element, or setting the title widget by
  * specifying “title” value.
  *
  * By default the `GtkHeaderBar` uses a `GtkLabel` displaying the title of the

gtk/gtklabel.c

@@ -94,7 +94,7 @@
  * # GtkLabel as GtkBuildable
  *
  * The GtkLabel implementation of the GtkBuildable interface supports a
- * custom <attributes> element, which supports any number of <attribute>
+ * custom `<attributes>` element, which supports any number of `<attribute>`
  * elements. The <attribute> element has attributes named “name“, “value“,
  * “start“ and “end“ and allows you to specify [struct@Pango.Attribute]
  * values for this label.

gtk/gtklevelbar.c

@@ -90,8 +90,8 @@
  * # GtkLevelBar as GtkBuildable
  *
  * The `GtkLevelBar` implementation of the `GtkBuildable` interface supports a
- * custom <offsets> element, which can contain any number of <offset> elements,
- * each of which must have name and value attributes.
+ * custom `<offsets>` element, which can contain any number of `<offset>` elements,
+ * each of which must have "name" and "value" attributes.
  *
  * # CSS nodes
  *

gtk/gtklistbase.c

@@ -378,10 +378,10 @@ gtk_list_base_get_allocation_across (GtkListBase *self,
  * @pos: item to select
  * @modify: %TRUE if the selection should be modified, %FALSE
  *   if a new selection should be done. This is usually set
- *   to %TRUE if the user keeps the <Shift> key pressed.
+ *   to %TRUE if the user keeps the `<Shift>` key pressed.
  * @extend_pos: %TRUE if the selection should be extended.
  *   Selections are usually extended from the last selected
- *   position if the user presses the <Ctrl> key.
+ *   position if the user presses the `<Ctrl>` key.
  *
  * Selects the item at @pos according to how GTK list widgets modify
  * selections, both when clicking rows with the mouse or when using

gtk/gtklistbox.c

@@ -66,7 +66,7 @@
  *
  * The `GtkListBox` implementation of the `GtkBuildable` interface supports
  * setting a child as the placeholder by specifying “placeholder” as the “type”
- * attribute of a <child> element. See [method@Gtk.ListBox.set_placeholder]
+ * attribute of a `<child>` element. See [method@Gtk.ListBox.set_placeholder]
  * for info.
  *
  * # CSS nodes

gtk/gtknotebook.c

@@ -77,14 +77,14 @@
  *
  * The `GtkNotebook` implementation of the `GtkBuildable` interface
  * supports placing children into tabs by specifying “tab” as the
- * “type” attribute of a <child> element. Note that the content
+ * “type” attribute of a `<child>` element. Note that the content
  * of the tab must be created before the tab can be filled.
- * A tab child can be specified without specifying a <child>
+ * A tab child can be specified without specifying a `<child>`
  * type attribute.
  *
  * To add a child widget in the notebooks action area, specify
  * "action-start" or “action-end” as the “type” attribute of the
- * <child> element.
+ * `<child>` element.
  *
  * An example of a UI definition fragment with `GtkNotebook`:
  *

gtk/gtkscale.c

@@ -64,8 +64,8 @@
  *
  * # GtkScale as GtkBuildable
  *
- * `GtkScale` supports a custom <marks> element, which can contain multiple
- * <mark\> elements. The “value” and “position” attributes have the same
+ * `GtkScale` supports a custom `<marks>` element, which can contain multiple
+ * `<mark\>` elements. The “value” and “position” attributes have the same
  * meaning as [method@Gtk.Scale.add_mark] parameters of the same name. If
  * the element is not empty, its content is taken as the markup to show at
  * the mark. It can be translated with the usual ”translatable” and

gtk/gtkshortcutsshortcut.c

@@ -555,22 +555,22 @@ gtk_shortcuts_shortcut_class_init (GtkShortcutsShortcutClass *klass)
    * by separating them with a space, but keep in mind that the available width
    * is limited.
    *
-   * It is also possible to specify ranges of shortcuts, using "..." between
-   * the keys. Sequences of keys can be specified using a "+" or "&" between
+   * It is also possible to specify ranges of shortcuts, using `...` between
+   * the keys. Sequences of keys can be specified using a `+` or `&` between
    * the keys.
    *
    * Examples:
    *
-   * - A single shortcut: <ctl><alt>delete
-   * - Two alternative shortcuts: <shift>a Home
-   * - A range of shortcuts: <alt>1...<alt>9
-   * - Several keys pressed together: Control_L&Control_R
-   * - A sequence of shortcuts or keys: <ctl>c+<ctl>x
+   * - A single shortcut: `<ctl><alt>delete`
+   * - Two alternative shortcuts: `<shift>a Home`
+   * - A range of shortcuts: `<alt>1...<alt>9`
+   * - Several keys pressed together: `Control_L&Control_R`
+   * - A sequence of shortcuts or keys: `<ctl>c+<ctl>x`
    *
    * Use "+" instead of "&" when the keys may (or have to be) pressed
    * sequentially (e.g use "t+t" for 'press the t key twice').
    *
-   * Note that <, > and & need to be escaped as &lt;, &gt; and &amp; when used
+   * Note that `<`, `>` and `&` need to be escaped as `&lt;`, `&gt`; and `&amp`; when used
    * in .ui files.
    */
   properties[PROP_ACCELERATOR] =

gtk/gtksizegroup.c

@@ -79,10 +79,10 @@
  *
  * # GtkSizeGroup as GtkBuildable
  *
- * Size groups can be specified in a UI definition by placing an <object>
+ * Size groups can be specified in a UI definition by placing an `<object>`
  * element with `class="GtkSizeGroup"` somewhere in the UI definition. The
- * widgets that belong to the size group are specified by a <widgets> element
- * that may contain multiple <widget> elements, one for each member of the
+ * widgets that belong to the size group are specified by a `<widgets>` element
+ * that may contain multiple `<widget>` elements, one for each member of the
  * size group. The ”name” attribute gives the id of the widget.
  *
  * An example of a UI definition fragment with `GtkSizeGroup`:

gtk/gtkstringlist.c

@@ -38,8 +38,8 @@
  * # GtkStringList as GtkBuildable
  *
  * The `GtkStringList` implementation of the `GtkBuildable` interface
- * supports adding items directly using the <items> element and
- * specifying <item> elements for each item. Each <item> element
+ * supports adding items directly using the `<items>` element and
+ * specifying `<item>` elements for each item. Each `<item>` element
  * supports the regular translation attributes “translatable”,
  * “context” and “comments”.
  *

gtk/gtktexttagtable.c

@@ -50,7 +50,7 @@
  *
  * The `GtkTextTagTable` implementation of the `GtkBuildable` interface
  * supports adding tags by specifying “tag” as the “type” attribute
- * of a <child> element.
+ * of a `<child>` element.
  *
  * An example of a UI definition fragment specifying tags:
  * ```xml

gtk/gtkwindow.c

@@ -119,7 +119,7 @@
  *
  * The `GtkWindow` implementation of the [iface@Gtk.Buildable] interface supports
  * setting a child as the titlebar by specifying “titlebar” as the “type”
- * attribute of a <child> element.
+ * attribute of a `<child>` element.
  *
  * # CSS nodes
  *