[gtk/wip/exalm/headerbar-title: 12/12] headerbar: Document GtkBuilder child types, add a title example

[Alexander Mikhaylenko <alexm src gnome org>]

commit b88e2f518a507f39f267344ec1eb93be5d588dd4
Author: Alexander Mikhaylenko <alexm gnome org>
Date:   Fri May 1 20:10:52 2020 +0500

    headerbar: Document GtkBuilder child types, add a title example

 gtk/gtkheaderbar.c | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
---
diff --git a/gtk/gtkheaderbar.c b/gtk/gtkheaderbar.c
index 5414cb56ce..25b0fcb7dc 100644
--- a/gtk/gtkheaderbar.c
+++ b/gtk/gtkheaderbar.c
@@ -57,6 +57,30 @@
  * titlebar widget of a #GtkWindow (see gtk_window_set_titlebar()), as it gives
  * features typical of titlebars while allowing the addition of child widgets.
  *
+ * 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, and setting the title by
+ * specifying “title” value.
+ *
+ * By default the GtkHeaderBar uses a #GtkLabel with window's title as a title
+ * widget, equivalent to the following UI definition:
+ *
+ * |[
+ * <object class="GtkHeaderBar">
+ *   <child type="title">
+ *     <object class="GtkLabel">
+ *       <property name="label" translatable="yes">Label</property>
+ *       <property name="single-line-mode">True</property>
+ *       <property name="ellipsize">end</property>
+ *       <property name="width-chars">5</property>
+ *       <style>
+ *         <class name="title"/>
+ *       </style>
+ *     </object>
+ *   </child>
+ * </object>
+ * ]|
+ *
  * # CSS nodes
  *
  * |[<!-- language="plain" -->