[gtk/nested-popover-menu] Document new api

[Matthias Clasen <matthiasc src gnome org>]

commit d7561810f2849f64d01665295eea85a5173a7065
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Sep 2 09:43:26 2019 +0100

    Document new api

 docs/reference/gtk/gtk4-sections.txt |  2 ++
 gtk/gtkpopovermenu.c                 | 27 +++++++++++++++++++++++++++
 gtk/gtkpopovermenu.h                 |  9 +++++++++
 3 files changed, 38 insertions(+)
---
diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt
index b72906d7ab..1b24d886da 100644
--- a/docs/reference/gtk/gtk4-sections.txt
+++ b/docs/reference/gtk/gtk4-sections.txt
@@ -1787,6 +1787,8 @@ gtk_map_list_model_get_type
 GtkMenu
 gtk_menu_new
 gtk_menu_new_from_model
+GtkPopoverMenuFlags
+gtk_menu_new_from_model_full
 gtk_menu_reorder_child
 gtk_menu_popup_at_rect
 gtk_menu_popup_at_widget
diff --git a/gtk/gtkpopovermenu.c b/gtk/gtkpopovermenu.c
index e059024460..93a34dd7d3 100644
--- a/gtk/gtkpopovermenu.c
+++ b/gtk/gtkpopovermenu.c
@@ -554,6 +554,10 @@ gtk_popover_menu_add_submenu (GtkPopoverMenu *popover,
  * Actions can also be added using gtk_widget_insert_action_group()
  * on the menus attach widget or on any of its parent widgets.
  *
+ * This function creates menus with sliding submenus.
+ * See gtk_popover_menu_new_from_model_full() for a way
+ * to control this.
+ *
  * Returns: the new #GtkPopoverMenu
  */
 GtkWidget *
@@ -564,6 +568,29 @@ gtk_popover_menu_new_from_model (GtkWidget  *relative_to,
   return gtk_popover_menu_new_from_model_full (relative_to, model, 0);
 }
 
+/**
+ * gtk_popover_menu_new_from_model_full:
+ * @relative_to: (allow-none): #GtkWidget the popover is related to
+ * @model: a #GMenuModel
+ * @flags: flags that affect how the menu is created
+ *
+ * Creates a #GtkPopoverMenu and populates it according to
+ * @model. The popover is pointed to the @relative_to widget.
+ *
+ * The created buttons are connected to actions found in the
+ * #GtkApplicationWindow to which the popover belongs - typically
+ * by means of being attached to a widget that is contained within
+ * the #GtkApplicationWindows widget hierarchy.
+ *
+ * Actions can also be added using gtk_widget_insert_action_group()
+ * on the menus attach widget or on any of its parent widgets.
+ *
+ * The only flag that is supported currently is
+ * #GTK_POPOVER_MENU_NESTED, which makes GTK create traditional,
+ * nested submenus instead of the default sliding submenus.
+ *
+ * Returns: the new #GtkPopoverMenu
+ */
 GtkWidget *
 gtk_popover_menu_new_from_model_full (GtkWidget           *relative_to,
                                       GMenuModel          *model,
diff --git a/gtk/gtkpopovermenu.h b/gtk/gtkpopovermenu.h
index 350bea6a4f..e2c1d3b3ef 100644
--- a/gtk/gtkpopovermenu.h
+++ b/gtk/gtkpopovermenu.h
@@ -42,6 +42,15 @@ GDK_AVAILABLE_IN_ALL
 GtkWidget * gtk_popover_menu_new_from_model (GtkWidget  *relative_to,
                                              GMenuModel *model);
 
+/**
+ * GtkPopoverMenuFlags:
+ * @GTK_POPOVER_MENU_NESTED: Create submenus as nested
+ *    popovers. Without this flag, submenus are created as
+ *    sliding pages that replace the main menu.
+ *
+ * Flags that affect how popover menus are created from
+ * a menu model.
+ */
 typedef enum {
   GTK_POPOVER_MENU_NESTED = 1 << 0
 } GtkPopoverMenuFlags;