diff --git a/gtk/gtkheaderbar.c b/gtk/gtkheaderbar.c
index ae85993464..a731cca328 100644
--- a/gtk/gtkheaderbar.c
+++ b/gtk/gtkheaderbar.c
@@ -51,6 +51,10 @@
  *
  * GtkHeaderBar can add typical window frame controls, such as minimize,
  * maximize and close buttons, or the window icon.
+ *
+ * For these reasons, GtkHeaderBar is the natural choice for use as the custom
+ * titlebar widget of a #GtkWindow (see gtk_window_set_titlebar()), as it gives
+ * features typical of titlebars while allowing the addition of child widgets.
  */
 
 #define DEFAULT_SPACING 6