diff --git a/gtk/gtkfontchooser.c b/gtk/gtkfontchooser.c
index 370b1a3109..bd99deee01 100644
--- a/gtk/gtkfontchooser.c
+++ b/gtk/gtkfontchooser.c
@@ -33,11 +33,10 @@
  * @See_also: #GtkFontChooserDialog, #GtkFontChooserWidget, #GtkFontButton
  *
  * #GtkFontChooser is an interface that can be implemented by widgets
- * displaying the list of fonts.  In GTK+, the main objects
+ * displaying the list of fonts. In GTK+, the main objects
  * that implement this interface are #GtkFontChooserWidget,
- * #GtkFontChooserDialog and #GtkFontButton.
- *
- * Since: 3.2
+ * #GtkFontChooserDialog and #GtkFontButton. The GtkFontChooser interface
+ * has been introducted in GTK+ 3.2.
  */
 
 enum
@@ -437,6 +436,27 @@ _gtk_font_chooser_font_activated (GtkFontChooser *chooser,
  * A custom font map can be used to present application-specific
  * fonts instead of or in addition to the normal system fonts.
  *
+ * |[<!-- language="C" -->
+ * FcConfig *config;
+ * PangoFontMap *fontmap;
+ *
+ * config = FcInitLoadConfigAndFonts ();
+ * FcConfigAppFontAddFile (config, my_app_font_file);
+ *
+ * fontmap = pango_cairo_font_map_new_for_font_type (CAIRO_FONT_TYPE_FT);
+ * pango_fc_font_map_set_config (PANGO_FC_FONT_MAP (fontmap), config);
+ *
+ * gtk_font_chooser_set_font_map (font_chooser, fontmap);
+ * ]|
+ *
+ * Note that other GTK+ widgets will only be able to use the application-specific
+ * font if it is present in the font map they use:
+ *
+ * |[
+ * context = gtk_widget_get_pango_context (label);
+ * pango_context_set_font_map (context, fontmap);
+ * ]|
+ *
  * Since: 3.18
  */
 void