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

[Alexander Mikhaylenko <alexm src gnome org>]

commit ab595621703ed5aac094a233ca2f01745259459e
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 | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)
---
diff --git a/gtk/gtkheaderbar.c b/gtk/gtkheaderbar.c
index 5414cb56ce..6952858ea0 100644
--- a/gtk/gtkheaderbar.c
+++ b/gtk/gtkheaderbar.c
@@ -57,6 +57,31 @@
  * 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, or setting the title widget by
+ * specifying “title” value.
+ *
+ * By default the GtkHeaderBar uses a #GtkLabel displaying the title of the
+ * window it is contained in as the title widget, equivalent to the following
+ * UI definition:
+ *
+ * |[
+ * <object class="GtkHeaderBar">
+ *   <property name="title-widget">
+ *     <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>
+ *   </property>
+ * </object>
+ * ]|
+ *
  * # CSS nodes
  *
  * |[<!-- language="plain" -->