Improve GObject introspection annotations (Fixes #8)

12 files changed, 248 insertions, 95 deletions

diff --git a/garcon-gtk/garcon-gtk-menu.c b/garcon-gtk/garcon-gtk-menu.c
index 593ed25..683752b 100644
--- a/garcon-gtk/garcon-gtk-menu.c
+++ b/garcon-gtk/garcon-gtk-menu.c
@@ -1003,7 +1003,7 @@ garcon_gtk_menu_set_menu (GarconGtkMenu *menu,
  * The caller is responsible to releasing the returned #GarconMenu
  * using g_object_unref().
  *
- * Returns: the #GarconMenu for @menu.
+ * Returns: (transfer full): the #GarconMenu for @menu.
  **/
 GarconMenu *
 garcon_gtk_menu_get_menu (GarconGtkMenu *menu)
diff --git a/garcon/garcon-config.c b/garcon/garcon-config.c
index 9f0c789..8a3916f 100644
--- a/garcon/garcon-config.c
+++ b/garcon/garcon-config.c
@@ -122,6 +122,12 @@ garcon_check_version (guint required_major,
 
 
 
+/**
+ * garcon_config_build_paths:
+ * @filename: name of .desktop file
+ *
+ * Returns: (transfer full):
+ */
 gchar **
 garcon_config_build_paths (const gchar *filename)
 {
diff --git a/garcon/garcon-menu-directory.c b/garcon/garcon-menu-directory.c
index bb1a32d..f8ba989 100644
--- a/garcon/garcon-menu-directory.c
+++ b/garcon/garcon-menu-directory.c
@@ -326,7 +326,7 @@ garcon_menu_directory_set_property (GObject      *object,
 
 
 /**
- * garcon_menu_directory_new:
+ * garcon_menu_directory_new: (method)
  * @file : a #GFile
  *
  * Create a new #GarconMenuDirectory for @file. You most likely never
@@ -392,12 +392,12 @@ garcon_menu_directory_new (GFile *file)
 
 /**
  * garcon_menu_directory_get_file:
- * @directory : a #GarconMenuDirectory
+ * @directory: a #GarconMenuDirectory
  *
- * Get the file for @directory.
+ * Get the #GFile for @directory. The returned object should be
+ * unreffed with g_object_unref() when no longer needed.
  *
- * Returns: a #GFile. The returned object
- * should be unreffed with g_object_unref() when no longer needed.
+ * Returns: (transfer full): a #GFile
  */
 GFile *
 garcon_menu_directory_get_file (GarconMenuDirectory *directory)
@@ -520,7 +520,7 @@ garcon_menu_directory_get_icon_name (GarconMenuDirectory *directory)
 /**
  * garcon_menu_directory_set_icon_name:
  * @directory : a #GarconMenuDirectory
- * @icon_name : the new icon name for @directory.
+ * @icon_name      : the new icon name for @directory.
  *
  * Set the icon name of @directory.
  */
diff --git a/garcon/garcon-menu-directory.h b/garcon/garcon-menu-directory.h
index f70ab3d..b3e90f1 100644
--- a/garcon/garcon-menu-directory.h
+++ b/garcon/garcon-menu-directory.h
@@ -68,7 +68,7 @@ void                 garcon_menu_directory_set_comment             (GarconMenuDi
                                                                     const gchar         *comment);
 const gchar         *garcon_menu_directory_get_icon_name           (GarconMenuDirectory *directory);
 void                 garcon_menu_directory_set_icon_name           (GarconMenuDirectory *directory,
-                                                                    const gchar         *icon);
+                                                                    const gchar         *icon_name);
 gboolean             garcon_menu_directory_get_no_display          (GarconMenuDirectory *directory);
 void                 garcon_menu_directory_set_no_display          (GarconMenuDirectory *directory,
                                                                     gboolean             no_display);
diff --git a/garcon/garcon-menu-item-cache.c b/garcon/garcon-menu-item-cache.c
index 6576b24..5b8a0dc 100644
--- a/garcon/garcon-menu-item-cache.c
+++ b/garcon/garcon-menu-item-cache.c
@@ -106,12 +106,12 @@ garcon_menu_item_cache_init (GarconMenuItemCache *cache)
 
 
 /**
- * garcon_menu_item_cache_get_default:
+ * garcon_menu_item_cache_get_default: (constructor)
  *
- * Returns the default #GarconMenuItemCache.
- *
- * Return value: the default #GarconMenuItemCache. The returned object
+ * Returns the default #GarconMenuItemCache. the returned object
  * should be unreffed with g_object_unref() when no longer needed.
+ *
+ * Returns: (transfer full): a new #GarconMenuItemCache.
  */
 GarconMenuItemCache*
 garcon_menu_item_cache_get_default (void)
@@ -152,7 +152,14 @@ garcon_menu_item_cache_finalize (GObject *object)
 }
 
 
-
+/**
+ * garcon_menu_item_cache_lookup:
+ * @cache: a #GarconMenuItemCache
+ * @uri:
+ * @desktop_id
+ *
+ * Returns: (transfer full) (nullable): a #GarconMenuItem
+ */
 GarconMenuItem*
 garcon_menu_item_cache_lookup (GarconMenuItemCache *cache,
                                const gchar         *uri,
@@ -203,7 +210,12 @@ garcon_menu_item_cache_lookup (GarconMenuItemCache *cache,
 }
 
 
-
+/**
+ * garcon_menu_item_cache_foreach:
+ * @cache: a #GarconMenuItemCache
+ * @func: (scope call):
+ * @user_data: parameter passed to @func callback
+ */
 void
 garcon_menu_item_cache_foreach (GarconMenuItemCache *cache,
                                 GHFunc               func,
diff --git a/garcon/garcon-menu-item-pool.c b/garcon/garcon-menu-item-pool.c
index 185733a..6232b0c 100644
--- a/garcon/garcon-menu-item-pool.c
+++ b/garcon/garcon-menu-item-pool.c
@@ -92,7 +92,11 @@ garcon_menu_item_pool_finalize (GObject *object)
 }
 
 
-
+/**
+ * garcon_menu_item_pool_new: (constructor)
+ *
+ * Returns: (transfer full): a #GarconMenuItemPool
+ */
 GarconMenuItemPool*
 garcon_menu_item_pool_new (void)
 {
@@ -100,7 +104,11 @@ garcon_menu_item_pool_new (void)
 }
 
 
-
+/**
+ * garcon_menu_item_pool_insert:
+ * @pool: a #GarconMenuItemPool
+ * @item: a #GarconMenuItem
+ */
 void
 garcon_menu_item_pool_insert (GarconMenuItemPool *pool,
                               GarconMenuItem     *item)
@@ -116,7 +124,13 @@ garcon_menu_item_pool_insert (GarconMenuItemPool *pool,
 }
 
 
-
+/**
+ * garcon_menu_item_pool_lookup:
+ * @pool: a #GarconMenuItemPool
+ * @desktop_id: (type filename): .desktop file
+ *
+ * Returns: (transfer full): a #GarconMenuItem object
+ */
 GarconMenuItem*
 garcon_menu_item_pool_lookup (GarconMenuItemPool *pool,
                               const gchar        *desktop_id)
@@ -128,7 +142,13 @@ garcon_menu_item_pool_lookup (GarconMenuItemPool *pool,
 }
 
 
-
+/**
+ * garcon_menu_item_pool_lookup_file:
+ * @pool: a #GarconMenuItemPool
+ * @file: a GFile instance
+ *
+ * Returns: (transfer full): a #GarconMenuItem object
+ */
 GarconMenuItem *
 garcon_menu_item_pool_lookup_file (GarconMenuItemPool *pool,
                                    GFile              *file)
@@ -156,7 +176,12 @@ garcon_menu_item_pool_lookup_file (GarconMenuItemPool *pool,
 }
 
 
-
+/**
+ * garcon_menu_item_pool_foreach:
+ * @pool: a #GarconMenuItemPool
+ * @func: (scope call):
+ * @user_data: user data passed to @func callback
+ */
 void
 garcon_menu_item_pool_foreach (GarconMenuItemPool *pool,
                                GHFunc              func,
diff --git a/garcon/garcon-menu-item.c b/garcon/garcon-menu-item.c
index c131878..311d6f5 100644
--- a/garcon/garcon-menu-item.c
+++ b/garcon/garcon-menu-item.c
@@ -707,7 +707,12 @@ garcon_menu_item_url_exec (XfceRc *rc)
 }
 
 
-
+/**
+ * garcon_menu_item_new: (constructor)
+ * @file: a #GFile
+ *
+ * Returns (transfer full): a new #GarconMenuItem
+ */
 GarconMenuItem *
 garcon_menu_item_new (GFile *file)
 {
@@ -911,7 +916,12 @@ garcon_menu_item_new (GFile *file)
 }
 
 
-
+/**
+ * garcon_menu_item_new_for_path: (constructor)
+ * @filename: (type filename): name of a file
+ *
+ * Returns: (transfer full): a new #GarconMenuItem
+ */
 GarconMenuItem *
 garcon_menu_item_new_for_path (const gchar *filename)
 {
@@ -928,7 +938,12 @@ garcon_menu_item_new_for_path (const gchar *filename)
 }
 
 
-
+/**
+ * garcon_menu_item_new_for_uri: (constructor)
+ * @uri: a given URI
+ *
+ * Returns: (transfer full): a new #GarconMenuItem
+ */
 GarconMenuItem *
 garcon_menu_item_new_for_uri (const gchar *uri)
 {
@@ -1244,11 +1259,12 @@ garcon_menu_item_reload_from_file (GarconMenuItem  *item,
 
 /**
  * garcon_menu_item_get_file:
+ * @item: A #GarconMenuItem
  *
- * Get the file for @item.
+ * Get the #GFile for @item. The returned object should be
+ * unreffed with g_object_unref() when no longer needed.
  *
- * Return value: a #GFile. The returned object
- * should be unreffed with g_object_unref() when no longer needed.
+ * Returns: (transfer full): a #GFile.
  */
 GFile *
 garcon_menu_item_get_file (GarconMenuItem *item)
@@ -1296,7 +1312,14 @@ garcon_menu_item_set_desktop_id (GarconMenuItem *item,
 }
 
 
-
+/**
+ * garcon_menu_item_get_categories:
+ * @item: a #GarconMenuItem
+ *
+ * Returns list of categories
+ *
+ * Returns: (element-type utf8) (transfer full):
+ */
 GList*
 garcon_menu_item_get_categories (GarconMenuItem *item)
 {
@@ -1305,7 +1328,11 @@ garcon_menu_item_get_categories (GarconMenuItem *item)
 }
 
 
-
+/**
+ * garcon_menu_item_set_categories:
+ * @item: a #GarconMenuItem
+ * @categories: (element-type utf8): list of categories
+ */
 void
 garcon_menu_item_set_categories (GarconMenuItem *item,
                                  GList          *categories)
@@ -1324,7 +1351,12 @@ garcon_menu_item_set_categories (GarconMenuItem *item,
 }
 
 
-
+/**
+ * garcon_menu_item_get_keywords:
+ * @item: a #GarconMenuItem
+ *
+ * Returns: (element-type utf8) (transfer full):
+ */
 GList*
 garcon_menu_item_get_keywords (GarconMenuItem *item)
 {
@@ -1333,7 +1365,11 @@ garcon_menu_item_get_keywords (GarconMenuItem *item)
 }
 
 
-
+/**
+ * garcon_menu_item_set_keywords:
+ * @item: a #GarconMenuItem
+ * @keywords: (element-type utf8): list of keywords
+ */
 void
 garcon_menu_item_set_keywords (GarconMenuItem *item,
                                GList          *keywords)
@@ -1352,7 +1388,6 @@ garcon_menu_item_set_keywords (GarconMenuItem *item,
 }
 
 
-
 const gchar*
 garcon_menu_item_get_command (GarconMenuItem *item)
 {
@@ -1361,7 +1396,6 @@ garcon_menu_item_get_command (GarconMenuItem *item)
 }
 
 
-
 void
 garcon_menu_item_set_command (GarconMenuItem *item,
                               const gchar    *command)
@@ -1709,7 +1743,12 @@ garcon_menu_item_has_keyword (GarconMenuItem *item,
 }
 
 
-
+/**
+ * garcon_menu_item_get_actions:
+ * @item: a #GarconMenuItem
+ *
+ * Returns: (element-type GarconMenuItemAction) (transfer full):
+ */
 GList *
 garcon_menu_item_get_actions (GarconMenuItem *item)
 {
@@ -1730,7 +1769,13 @@ garcon_menu_item_get_actions (GarconMenuItem *item)
 }
 
 
-
+/**
+ * garcon_menu_item_get_action:
+ * @item: a #GarconMenuItem
+ * @action_name:
+ *
+ * Returns: (nullable) (transfer full): a #GarconMenuItemAction
+ */
 GarconMenuItemAction *
 garcon_menu_item_get_action (GarconMenuItem *item,
                              const gchar    *action_name)
diff --git a/garcon/garcon-menu-merger.c b/garcon/garcon-menu-merger.c
index 0e210f4..5e31ccf 100644
--- a/garcon/garcon-menu-merger.c
+++ b/garcon/garcon-menu-merger.c
@@ -262,7 +262,15 @@ garcon_menu_merger_prepare_merging (GarconMenuMerger        *merger,
 }
 
 
-
+/**
+ * garcon_menu_merger_run:
+ * @merger: a #GarconMenuMerger
+ * @merge_files: (element-type utf8): list of files to merge
+ * @merge_dirs: (element-type utf8): list of menu directories to merge
+ * @cancellable:
+ * @error:
+ *
+ */
 gboolean
 garcon_menu_merger_run (GarconMenuMerger *merger,
                         GList           **merge_files,
diff --git a/garcon/garcon-menu-node.c b/garcon/garcon-menu-node.c
index 955c1e6..4008663 100644
--- a/garcon/garcon-menu-node.c
+++ b/garcon/garcon-menu-node.c
@@ -232,7 +232,14 @@ GarconMenuNodeType garcon_menu_node_get_node_type (GarconMenuNode *node)
 }
 
 
-
+/**
+ * garcon_menu_node_create:
+ * @node_type: a #GarconMenuNodeType
+ * @first_value:
+ * @...:
+ *
+ * Returns: (transfer full): a #GarconMenuNode
+ */
 GarconMenuNode *
 garcon_menu_node_create (GarconMenuNodeType node_type,
                          gpointer           first_value,
@@ -274,7 +281,13 @@ garcon_menu_node_create (GarconMenuNodeType node_type,
 }
 
 
-
+/**
+ * garcon_menu_node_copy:
+ * @node: a #GarconMenuNode
+ * @data:
+ *
+ * Returns: (transfer full): a #GarconMenuNode
+ */
 GarconMenuNode *
 garcon_menu_node_copy (GarconMenuNode *node,
                        gpointer        data)
@@ -440,13 +453,20 @@ collect_children (GNode *node,
 }
 
 
-
+/**
+ * garcon_menu_node_tree_get_child_node: (skip)
+ * @tree: #GNode instance
+ * @type: type for the menu nodes
+ * @reverse:
+ *
+ * Returns: a #GNode if @type is valid menu nodes type.
+ */
 GNode *
 garcon_menu_node_tree_get_child_node (GNode             *tree,
                                       GarconMenuNodeType type,
                                       gboolean           reverse)
 {
-  GNode *child;
+  GNode *child = NULL;
 
   if (reverse)
     {
@@ -469,11 +489,18 @@ garcon_menu_node_tree_get_child_node (GNode             *tree,
         }
     }
 
-  return NULL;
+  return child;
 }
 
 
-
+/**
+ * garcon_menu_node_tree_get_child_nodes:
+ * @tree: a GNode
+ * @type: type for the menu nodes
+ * @reverse:
+ *
+ * Returns: (element-type GNode) (transfer full): list of #GNode
+ */
 GList *
 garcon_menu_node_tree_get_child_nodes (GNode             *tree,
                                        GarconMenuNodeType type,
@@ -492,7 +519,7 @@ garcon_menu_node_tree_get_child_nodes (GNode             *tree,
   if (!reverse && pair.value != NULL)
     pair.value = g_list_reverse (pair.value);
 
-  return pair.value;
+  return (GList *) pair.value;
 }
 
 
@@ -516,7 +543,14 @@ collect_strings (GNode *node,
 }
 
 
-
+/**
+ * garcon_menu_node_tree_get_string_children:
+ * @tree: a #GNode instance
+ * @type: type for the menu nodes
+ * @reverse:
+ *
+ * Returns: (element-type GNode) (transfer full): list of #GNode
+ */
 GList *
 garcon_menu_node_tree_get_string_children (GNode             *tree,
                                            GarconMenuNodeType type,
@@ -535,7 +569,7 @@ garcon_menu_node_tree_get_string_children (GNode             *tree,
   if (!reverse && pair.value != NULL)
     pair.value = g_list_reverse (pair.value);
 
-  return pair.value;
+  return (GList *) pair.value;
 }
 
 
@@ -799,7 +833,12 @@ garcon_menu_node_tree_compare (GNode *tree,
 }
 
 
-
+/**
+ * garcon_menu_node_tree_copy: (skip)
+ * @tree: a #GNode
+ *
+ * Recursively copies a #GNode.
+ */
 GNode *
 garcon_menu_node_tree_copy (GNode *tree)
 {
diff --git a/garcon/garcon-menu-separator.c b/garcon/garcon-menu-separator.c
index 92366c0..c082552 100644
--- a/garcon/garcon-menu-separator.c
+++ b/garcon/garcon-menu-separator.c
@@ -87,17 +87,17 @@ garcon_menu_separator_finalize (GObject *object)
 
 
 /**
- * garcon_menu_separator_get_default:
+ * garcon_menu_separator_get_default: (constructor)
  *
- * Returns the default #GarconMenuSeparator.
- *
- * Return value: the default #GarconMenuSeparator. The returned object
+ * Returns a new #GarconMenuSeparator. The returned object
  * should be unreffed with g_object_unref() when no longer needed.
+ *
+ * Returns: (transfer full): a new #GarconMenuSeparator.
  */
 GarconMenuSeparator*
 garcon_menu_separator_get_default (void)
 {
-  static GarconMenuSeparator *separator = NULL;
+  GarconMenuSeparator *separator = NULL;
 
   if (G_UNLIKELY (separator == NULL))
     {
diff --git a/garcon/garcon-menu-tree-provider.c b/garcon/garcon-menu-tree-provider.c
index 14e2695..03f31b5 100644
--- a/garcon/garcon-menu-tree-provider.c
+++ b/garcon/garcon-menu-tree-provider.c
@@ -51,7 +51,12 @@ garcon_menu_tree_provider_get_type (void)
 }
 
 
-
+/**
+ * garcon_menu_tree_provider_get_tree: (skip)
+ * @provider: a #GarconMenuTreeProvider
+ *
+ * Returns: a #GNode
+ */
 GNode *
 garcon_menu_tree_provider_get_tree (GarconMenuTreeProvider *provider)
 {
@@ -60,7 +65,12 @@ garcon_menu_tree_provider_get_tree (GarconMenuTreeProvider *provider)
 }
 
 
-
+/**
+ * garcon_menu_tree_provider_get_file:
+ * @provider: a #GarconMenuTreeProvider
+ *
+ * Returns: (transfer full):
+ */
 GFile *
 garcon_menu_tree_provider_get_file (GarconMenuTreeProvider *provider)
 {
diff --git a/garcon/garcon-menu.c b/garcon/garcon-menu.c
index 2f9dfbd..7031d61 100644
--- a/garcon/garcon-menu.c
+++ b/garcon/garcon-menu.c
@@ -460,8 +460,8 @@ garcon_menu_set_property (GObject      *object,
 
 
 /**
- * garcon_menu_new:
- * @file  : #GFile for the .menu file you want to load.
+ * garcon_menu_new: (constructor)
+ * @file: #GFile for the .menu file you want to load.
  *
  * Creates a new #GarconMenu for the .menu file referred to by @file.
  * This operation only fails @file is invalid. To load the menu
@@ -473,7 +473,7 @@ garcon_menu_set_property (GObject      *object,
  *
  * For more information about the usage @see garcon_menu_new().
  *
- * Returns: a new #GarconMenu for @file.
+ * Returns: (transfer full): a new #GarconMenu.
  **/
 GarconMenu *
 garcon_menu_new (GFile *file)
@@ -485,7 +485,7 @@ garcon_menu_new (GFile *file)
 
 
 /**
- * garcon_menu_new_for_path:
+ * garcon_menu_new_for_path: (constructor)
  * @filename : Path/URI of the .menu file you want to load.
  *
  * Creates a new #GarconMenu for the .menu file referred to by @filename.
@@ -507,7 +507,8 @@ garcon_menu_new (GFile *file)
  * The caller is responsible to destroy the returned #GarconMenu
  * using g_object_unref().
  *
- * Returns: a new #GarconMenu for @filename.
+ * Returns: (transfer full): a new #GarconMenu
+ * for @filename.
  **/
 GarconMenu *
 garcon_menu_new_for_path (const gchar *filename)
@@ -535,7 +536,8 @@ garcon_menu_new_for_path (const gchar *filename)
  *
  * For more information about the usage @see garcon_menu_new().
  *
- * Returns: a new #GarconMenu for applications.menu.
+ * Returns: (transfer full): a new #GarconMenu
+ * for applications.menu.
  **/
 GarconMenu *
 garcon_menu_new_applications (void)
@@ -552,13 +554,15 @@ garcon_menu_new_applications (void)
 
 /**
  * garcon_menu_get_file:
- * @menu : a #GarconMenu.
+ * @menu: a #GarconMenu.
  *
  * Get the file for @menu. It refers to the .menu file from which
  * @menu was or will be loaded.
  *
- * Returns: a #GFile. The returned object
- *          should be unreffed with g_object_unref() when no longer needed.
+ * The returned object should be unreffed with g_object_unref()
+ * when no longer needed.
+ *
+ * Returns: (transfer full): a #GFile.
  */
 GFile *
 garcon_menu_get_file (GarconMenu *menu)
@@ -582,17 +586,19 @@ garcon_menu_get_name (GarconMenu *menu)
 
 /**
  * garcon_menu_get_directory:
- * @menu : a #GarconMenu.
+ * @menu: a #GarconMenu.
+ *
+ * Returns the #GarconMenuDirectory of @menu or %NULL if @menu has
+ * no valid directory element.
+ *
+ * The returned object should be unreffed with g_object_unref() when
+ * no longer needed.
  *
- * Returns the #GarconMenuDirectory of @menu or %NULL if the <Menu>
- * element that corresponds to @menu has no valid <Directory> element.
  * The menu directory may contain a lot of useful information about
  * the menu like the display and icon name, desktop environments it
  * should show up in etc.
  *
- * Returns: #GarconMenuDirectory of @menu or %NULL if
- *          @menu has no valid directory element. The returned object
- *          should be unreffed with g_object_unref() when no longer needed.
+ * Returns: (transfer full) (nullable): a #GarconMenuDirectory
  */
 GarconMenuDirectory*
 garcon_menu_get_directory (GarconMenu *menu)
@@ -770,13 +776,14 @@ garcon_menu_load (GarconMenu   *menu,
 
 /**
  * garcon_menu_get_menus:
- * @menu : a #GarconMenu
+ * @menu: a #GarconMenu
  *
- * Returns a sorted list of #GarconMenu submenus of @menu.
+ * Returns a sorted list of #GarconMenu submenus of @menu. The list
+ * should be freed with g_list_free().
  *
- * Returns: a sorted list of #GarconMenu object. The list should
- *          be freed with g_list_free().
- **/
+ * Returns: (transfer full) (element-type GarconMenu): a sorted list
+ * of #GarconMenu.
+ */
 GList *
 garcon_menu_get_menus (GarconMenu *menu)
 {
@@ -797,8 +804,8 @@ garcon_menu_get_menus (GarconMenu *menu)
 
 /**
  * garcon_menu_add_menu:
- * @menu    : a #GarconMenu
- * @submenu : a #GarconMenu
+ * @menu:    a #GarconMenu
+ * @submenu: a #GarconMenu
  *
  * Adds @submenu as a sub menu to @menu.
  **/
@@ -823,13 +830,13 @@ garcon_menu_add_menu (GarconMenu *menu,
 
 /**
  * garcon_menu_get_menu_with_name:
- * @menu : a #GarconMenu
- * @name : a sub menu name
+ * @menu: a #GarconMenu
+ * @name: a sub menu name
  *
  * Looks in @menu for a submenu with @name as name.
  *
- * Returns: a #GarconMenu or %NULL.
- **/
+ * Returns: (transfer full) (nullable): a #GarconMenu or %NULL.
+ */
 GarconMenu *
 garcon_menu_get_menu_with_name (GarconMenu  *menu,
                                 const gchar *name)
@@ -855,12 +862,13 @@ garcon_menu_get_menu_with_name (GarconMenu  *menu,
 
 /**
  * garcon_menu_get_parent:
- * @menu : a #GarconMenu
+ * @menu: a #GarconMenu
  *
  * Returns the parent #GarconMenu or @menu.
  *
- * Returns: a #GarconMenu or %NULL if @menu is the root menu.
- **/
+ * Returns: (transfer full) (nullable): a #GarconMenu or %NULL
+ * if @menu is the root menu.
+ */
 GarconMenu *
 garcon_menu_get_parent (GarconMenu *menu)
 {
@@ -1351,13 +1359,13 @@ garcon_menu_remove_deleted_menus (GarconMenu *menu)
 
 /**
  * garcon_menu_get_item_pool:
- * @menu : a #GarconMenu.
+ * @menu: a #GarconMenu.
  *
  * Get the item pool of the menu. This pool contains all items in this
  * menu (for that of its submenus).
  *
- * Returns: a #GarconMenuItemPool.
- **/
+ * Returns: (transfer full): a #GarconMenuItemPool.
+ */
 GarconMenuItemPool*
 garcon_menu_get_item_pool (GarconMenu *menu)
 {
@@ -1380,19 +1388,17 @@ items_collect (const gchar    *desktop_id,
 
 /**
  * garcon_menu_get_items:
- * @menu : a #GarconMenu.
+ * @menu: a #GarconMenu.
  *
- * Returns all #GarconMenuItem<!---->s included in @menu. The items are
+ * Returns all #GarconMenuItem included in @menu. The items are
  * sorted by their display names in ascending order.
  *
  * The caller is responsible to free the returned list using
- * <informalexample><programlisting>
- * g_list_free (list);
- * </programlisting></informalexample>
- * when no longer needed.
+ * g_list_free() when no longer needed.
  *
- * Returns: list of #GarconMenuItem<!---->s included in @menu.
- **/
+ * Returns: (element-type GarconMenuItem) (transfer full): list
+ * of #GarconMenuItem included in @menu.
+ */
 GList *
 garcon_menu_get_items (GarconMenu *menu)
 {
@@ -1511,14 +1517,16 @@ layout_elements_collect (GList **dest_list,
 
 /**
  * garcon_menu_get_elements:
- * @menu : a #GarconMenu.
+ * @menu: a #GarconMenu.
  *
  * Get all the menu element in @menu. This contains sub menus, menu items
  * and separators.
  *
- * Returns: a list of #GarconMenuItem elements or %NULL. Free the list
- *          with g_list_free().
- **/
+ * Returns a list of #GarconMenuItem or %NULL. Free the list with
+ * g_list_free().
+ *
+ * Returns: (element-type GarconMenuItem) (nullable) (transfer full):
+ */
 GList *
 garcon_menu_get_elements (GarconMenu *menu)
 {