From 9735f8afe6d5bf5d8680fcce4040cbc09da909d2 Mon Sep 17 00:00:00 2001 From: Olivier Duchateau Date: Fri, 15 Feb 2019 18:39:22 +0100 Subject: [PATCH] Improve GObject introspection annotations --- garcon-gtk/garcon-gtk-menu.c | 2 +- garcon/garcon-config.c | 6 ++ garcon/garcon-menu-directory.c | 18 +++--- garcon/garcon-menu-item-cache.c | 24 ++++++-- garcon/garcon-menu-item-pool.c | 35 +++++++++-- garcon/garcon-menu-item.c | 73 ++++++++++++++++++----- garcon/garcon-menu-merger.c | 10 +++- garcon/garcon-menu-node.c | 59 ++++++++++++++---- garcon/garcon-menu-separator.c | 10 ++-- garcon/garcon-menu-tree-provider.c | 14 ++++- garcon/garcon-menu.c | 96 ++++++++++++++++-------------- 11 files changed, 250 insertions(+), 97 deletions(-) diff --git a/garcon-gtk/garcon-gtk-menu.c b/garcon-gtk/garcon-gtk-menu.c index 665e253..ba7b14c 100644 --- a/garcon-gtk/garcon-gtk-menu.c +++ b/garcon-gtk/garcon-gtk-menu.c @@ -1069,7 +1069,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 deb62ba..b4b434f 100644 --- a/garcon/garcon-menu-directory.c +++ b/garcon/garcon-menu-directory.c @@ -328,7 +328,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 @@ -394,12 +394,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) @@ -522,24 +522,24 @@ 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 : the new icon name for @directory. * * Set the icon name of @directory. */ void garcon_menu_directory_set_icon_name (GarconMenuDirectory *directory, - const gchar *icon_name) + const gchar *icon) { g_return_if_fail (GARCON_IS_MENU_DIRECTORY (directory)); - if (g_strcmp0 (directory->priv->icon_name, icon_name) == 0) + if (g_strcmp0 (directory->priv->icon_name, icon) == 0) return; /* Free old name */ g_free (directory->priv->icon_name); /* Set the new filename */ - directory->priv->icon_name = g_strdup (icon_name); + directory->priv->icon_name = g_strdup (icon); /* Notify listeners */ g_object_notify (G_OBJECT (directory), "icon-name"); diff --git a/garcon/garcon-menu-item-cache.c b/garcon/garcon-menu-item-cache.c index 5d722ed..c86ef4a 100644 --- a/garcon/garcon-menu-item-cache.c +++ b/garcon/garcon-menu-item-cache.c @@ -107,12 +107,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) @@ -153,7 +153,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, @@ -204,7 +211,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 355e520..0236515 100644 --- a/garcon/garcon-menu-item-pool.c +++ b/garcon/garcon-menu-item-pool.c @@ -93,7 +93,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) { @@ -101,7 +105,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) @@ -117,7 +125,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) @@ -129,7 +143,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) @@ -157,7 +177,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 4382e9b..b413331 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) { @@ -915,7 +920,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) { @@ -932,7 +942,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) { @@ -1246,11 +1261,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) @@ -1298,7 +1314,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) { @@ -1307,7 +1330,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) @@ -1326,7 +1353,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) { @@ -1335,7 +1367,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) @@ -1354,7 +1390,6 @@ garcon_menu_item_set_keywords (GarconMenuItem *item, } - const gchar* garcon_menu_item_get_command (GarconMenuItem *item) { @@ -1363,7 +1398,6 @@ garcon_menu_item_get_command (GarconMenuItem *item) } - void garcon_menu_item_set_command (GarconMenuItem *item, const gchar *command) @@ -1711,7 +1745,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) { @@ -1732,7 +1771,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 24537de..615c292 100644 --- a/garcon/garcon-menu-merger.c +++ b/garcon/garcon-menu-merger.c @@ -261,7 +261,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 ac7cdcc..23626ca 100644 --- a/garcon/garcon-menu.c +++ b/garcon/garcon-menu.c @@ -461,8 +461,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 @@ -474,7 +474,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) @@ -486,7 +486,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. @@ -508,7 +508,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) @@ -536,7 +537,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) @@ -553,13 +555,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) @@ -583,17 +587,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) @@ -771,13 +777,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) { @@ -798,8 +805,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. **/ @@ -824,13 +831,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) @@ -856,12 +863,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) { @@ -1352,13 +1360,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) { @@ -1381,19 +1389,17 @@ items_collect (const gchar *desktop_id, /** * garcon_menu_get_items: - * @menu : a #GarconMenu. + * @menu: a #GarconMenu. * - * Returns all #GarconMenuItems 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 - * - * g_list_free (list); - * - * when no longer needed. + * g_list_free() when no longer needed. * - * Returns: list of #GarconMenuItems included in @menu. - **/ + * Returns: (element-type GarconMenuItem) (transfer full): list + * of #GarconMenuItem included in @menu. + */ GList * garcon_menu_get_items (GarconMenu *menu) { @@ -1512,14 +1518,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) { -- 2.20.1