docs: Reorganize and fix

This commit completes the sections file with subsections, moves most
documentation to headers (no real reason to, especially given that
changes there may cause unwanted rebuilds, but it feels better to have
it in the headers) and fixes some annotations.

Closes https://gitlab.gnome.org/GNOME/nautilus/issues/565

1 files changed, 65 insertions, 2 deletions

diff --git a/libnautilus-extension/nautilus-menu.h b/libnautilus-extension/nautilus-menu.h
index bbf71fa88..d699e1c95 100644
--- a/libnautilus-extension/nautilus-menu.h
+++ b/libnautilus-extension/nautilus-menu.h
@@ -44,6 +44,25 @@ G_DECLARE_DERIVABLE_TYPE (NautilusMenuItem, nautilus_menu_item,
                           NAUTILUS, MENU_ITEM,
                           GObject)
 
+/**
+ * SECTION:nautilus-menu
+ * @title: NautilusMenu
+ * @short_description: Menu descriptor object
+ *
+ * #NautilusMenu is an object that describes a submenu in a file manager
+ * menu. Extensions can provide #NautilusMenu objects by attaching them to
+ * #NautilusMenuItem objects, using nautilus_menu_item_set_submenu().
+ *
+ * ## Menu Items
+ *
+ * #NautilusMenuItem is an object that describes an item in a file manager
+ * menu. Extensions can provide #NautilusMenuItem objects by registering a
+ * #NautilusMenuProvider and returning them from
+ * nautilus_menu_provider_get_file_items(), or
+ * nautilus_menu_provider_get_background_items(), which will be called by the
+ * main application when creating menus.
+ */
+
 struct _NautilusMenuItemClass
 {
     GObjectClass parent;
@@ -51,20 +70,64 @@ struct _NautilusMenuItemClass
     void (*activate) (NautilusMenuItem *item);
 };
 
+/**
+ * nautilus_menu_new:
+ *
+ * Returns: a new #NautilusMenu.
+ */
 NautilusMenu     *nautilus_menu_new              (void);
 
+/**
+ * nautilus_menu_append_item:
+ * @menu: a #NautilusMenu
+ * @item: (transfer full): a #NautilusMenuItem to append
+ */
 void              nautilus_menu_append_item      (NautilusMenu     *menu,
                                                   NautilusMenuItem *item);
+/**
+ * nautilus_menu_get_items:
+ * @menu: a #NautilusMenu
+ *
+ * Returns: (element-type NautilusMenuItem) (transfer full): the provided #NautilusMenuItem list
+ */
 GList            *nautilus_menu_get_items        (NautilusMenu     *menu);
+/**
+ * nautilus_menu_item_list_free:
+ * @item_list: (element-type NautilusMenuItem): a list of #NautilusMenuItem
+ *
+ */
 void              nautilus_menu_item_list_free   (GList            *item_list);
 
-
+/**
+ * nautilus_menu_item_new:
+ * @name: the identifier for the menu item
+ * @label: the user-visible label of the menu item
+ * @tip: the tooltip of the menu item
+ * @icon: the name of the icon to display in the menu item
+ *
+ * Creates a new menu item that can be added to the toolbar or to a contextual menu.
+ *
+ * Returns: (transfer full): a new #NautilusMenuItem
+ */
 NautilusMenuItem *nautilus_menu_item_new         (const char       *name,
                                                   const char       *label,
                                                   const char       *tip,
                                                   const char       *icon);
 
+/**
+ * nautilus_menu_item_activate:
+ * @item: pointer to a #NautilusMenuItem
+ *
+ * Emits #NautilusMenuItem::activate.
+ */
 void              nautilus_menu_item_activate    (NautilusMenuItem *item);
+/**
+ * nautilus_menu_item_set_submenu:
+ * @item: pointer to a #NautilusMenuItem
+ * @menu: (transfer full): pointer to a #NautilusMenu to attach to the button
+ *
+ * Attaches a menu to the given #NautilusMenuItem.
+ */
 void              nautilus_menu_item_set_submenu (NautilusMenuItem *item,
                                                   NautilusMenu     *menu);
 
@@ -79,4 +142,4 @@ void              nautilus_menu_item_set_submenu (NautilusMenuItem *item,
  *   menu (NautilusMenu)  - The menu belonging to this item. May be null.
  */
 
-G_END_DECLS
\ No newline at end of file
+G_END_DECLS