[Xfce4-commits] <garcon:master> API documentation updates.
Nick Schermer
noreply at xfce.org
Fri Feb 26 16:16:02 CET 2010
Updating branch refs/heads/master
to 9bceacea5119fa5f68785ddb5d770c80f18d2052 (commit)
from 57bd4be54c513aa6d6292f3a7fc2e5cb4036db21 (commit)
commit 9bceacea5119fa5f68785ddb5d770c80f18d2052
Author: Nick Schermer <nick at xfce.org>
Date: Fri Feb 26 14:56:10 2010 +0100
API documentation updates.
docs/reference/garcon-docs.xml | 10 --
docs/reference/garcon-sections.txt | 245 +++++++++++++++++-------------------
garcon/garcon-config.c | 68 +++++++++-
garcon/garcon-config.h.in | 37 ++++++
garcon/garcon-environment.c | 14 ++-
garcon/garcon-menu-directory.c | 128 ++++++++++++++++++-
garcon/garcon-menu-element.c | 12 ++
garcon/garcon-menu.c | 84 ++++++++++--
8 files changed, 434 insertions(+), 164 deletions(-)
diff --git a/docs/reference/garcon-docs.xml b/docs/reference/garcon-docs.xml
index 721518a..7203278 100644
--- a/docs/reference/garcon-docs.xml
+++ b/docs/reference/garcon-docs.xml
@@ -75,16 +75,10 @@
<xi:include href="xml/garcon-menu-tree-provider.xml"/>
</part>
- <part id="garcon-monitoring">
- <title>Monitoring</title>
- <xi:include href="xml/garcon-menu-monitor.xml"/>
- </part>
-
<part id="garcon-miscellaneous">
<title>Miscellaneous</title>
<xi:include href="xml/garcon-environment.xml"/>
<xi:include href="xml/garcon.xml"/>
- <xi:include href="xml/garcon-gio.xml"/>
<xi:include href="xml/garcon-config.xml"/>
</part>
@@ -99,8 +93,4 @@
<xi:fallback />
</xi:include>
</index>
-
- <xi:include href="xml/annotation-glossary.xml">
- <xi:fallback />
- </xi:include>
</book>
diff --git a/docs/reference/garcon-sections.txt b/docs/reference/garcon-sections.txt
index c3e6435..d9b5332 100644
--- a/docs/reference/garcon-sections.txt
+++ b/docs/reference/garcon-sections.txt
@@ -1,6 +1,6 @@
<SECTION>
<FILE>garcon-menu</FILE>
-GarconMenuPrivate
+GarconMenu
garcon_menu_new
garcon_menu_new_for_path
garcon_menu_new_applications
@@ -14,9 +14,9 @@ garcon_menu_get_parent
garcon_menu_get_item_pool
garcon_menu_get_items
garcon_menu_get_elements
-<TITLE>GarconMenu</TITLE>
-GarconMenu
<SUBSECTION Standard>
+GarconMenuClass
+GarconMenuPrivate
GARCON_MENU
GARCON_IS_MENU
GARCON_TYPE_MENU
@@ -27,25 +27,28 @@ GARCON_MENU_GET_CLASS
</SECTION>
<SECTION>
-<FILE>garcon-menu-tree-provider</FILE>
-GarconMenuTreeProviderIface
-GarconMenuTreeProvider
-garcon_menu_tree_provider_get_tree
-garcon_menu_tree_provider_get_file
+<FILE>garcon-menu-merger</FILE>
+GarconMenuMerger
+garcon_menu_merger_new
+garcon_menu_merger_run
<SUBSECTION Standard>
-GARCON_MENU_TREE_PROVIDER
-GARCON_IS_MENU_TREE_PROVIDER
-GARCON_TYPE_MENU_TREE_PROVIDER
-garcon_menu_tree_provider_get_type
-GARCON_MENU_TREE_PROVIDER_GET_IFACE
+GarconMenuMergerClass
+GarconMenuMergerPrivate
+GARCON_MENU_MERGER
+GARCON_IS_MENU_MERGER
+GARCON_TYPE_MENU_MERGER
+garcon_menu_merger_get_type
+GARCON_MENU_MERGER_CLASS
+GARCON_IS_MENU_MERGER_CLASS
+GARCON_MENU_MERGER_GET_CLASS
</SECTION>
<SECTION>
<FILE>garcon-menu-separator</FILE>
-<TITLE>GarconMenuSeparator</TITLE>
GarconMenuSeparator
garcon_menu_separator_get_default
<SUBSECTION Standard>
+GarconMenuSeparatorClass
GARCON_MENU_SEPARATOR
GARCON_IS_MENU_SEPARATOR
GARCON_TYPE_MENU_SEPARATOR
@@ -56,23 +59,6 @@ GARCON_MENU_SEPARATOR_GET_CLASS
</SECTION>
<SECTION>
-<FILE>garcon-menu-parser</FILE>
-GarconMenuParserPrivate
-garcon_menu_parser_new
-garcon_menu_parser_run
-<TITLE>GarconMenuParser</TITLE>
-GarconMenuParser
-<SUBSECTION Standard>
-GARCON_MENU_PARSER
-GARCON_IS_MENU_PARSER
-GARCON_TYPE_MENU_PARSER
-garcon_menu_parser_get_type
-GARCON_MENU_PARSER_CLASS
-GARCON_IS_MENU_PARSER_CLASS
-GARCON_MENU_PARSER_GET_CLASS
-</SECTION>
-
-<SECTION>
<FILE>garcon-menu-node</FILE>
GarconMenuNodeType
GarconMenuLayoutMergeType
@@ -118,26 +104,107 @@ GARCON_MENU_NODE_GET_CLASS
</SECTION>
<SECTION>
-<FILE>garcon-menu-merger</FILE>
-GarconMenuMergerPrivate
-garcon_menu_merger_new
-garcon_menu_merger_run
-<TITLE>GarconMenuMerger</TITLE>
-GarconMenuMerger
+<FILE>garcon-menu-directory</FILE>
+GarconMenuDirectory
+garcon_menu_directory_new
+garcon_menu_directory_get_file
+garcon_menu_directory_get_name
+garcon_menu_directory_set_name
+garcon_menu_directory_get_comment
+garcon_menu_directory_set_comment
+garcon_menu_directory_get_icon_name
+garcon_menu_directory_set_icon_name
+garcon_menu_directory_get_no_display
+garcon_menu_directory_set_no_display
+garcon_menu_directory_get_hidden
+garcon_menu_directory_get_show_in_environment
+garcon_menu_directory_get_visible
+garcon_menu_directory_equal
<SUBSECTION Standard>
-GARCON_MENU_MERGER
-GARCON_IS_MENU_MERGER
-GARCON_TYPE_MENU_MERGER
-garcon_menu_merger_get_type
-GARCON_MENU_MERGER_CLASS
-GARCON_IS_MENU_MERGER_CLASS
-GARCON_MENU_MERGER_GET_CLASS
+GarconMenuDirectoryPrivate
+GarconMenuDirectoryClass
+GARCON_MENU_DIRECTORY
+GARCON_IS_MENU_DIRECTORY
+GARCON_TYPE_MENU_DIRECTORY
+garcon_menu_directory_get_type
+GARCON_MENU_DIRECTORY_CLASS
+GARCON_IS_MENU_DIRECTORY_CLASS
+GARCON_MENU_DIRECTORY_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>garcon-menu-item-cache</FILE>
+GarconMenuItemCache
+garcon_menu_item_cache_get_default
+garcon_menu_item_cache_lookup
+garcon_menu_item_cache_foreach
+garcon_menu_item_cache_invalidate
+<SUBSECTION Standard>
+GarconMenuItemCachePrivate
+GarconMenuItemCacheClass
+GARCON_MENU_ITEM_CACHE
+GARCON_IS_MENU_ITEM_CACHE
+GARCON_TYPE_MENU_ITEM_CACHE
+garcon_menu_item_cache_get_type
+GARCON_MENU_ITEM_CACHE_CLASS
+GARCON_IS_MENU_ITEM_CACHE_CLASS
+GARCON_MENU_ITEM_CACHE_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>garcon-menu-parser</FILE>
+garcon_menu_parser_new
+garcon_menu_parser_run
+GarconMenuParser
+<SUBSECTION Standard>
+GarconMenuParserPrivate
+GarconMenuParserClass
+GARCON_MENU_PARSER
+GARCON_IS_MENU_PARSER
+GARCON_TYPE_MENU_PARSER
+garcon_menu_parser_get_type
+GARCON_MENU_PARSER_CLASS
+GARCON_IS_MENU_PARSER_CLASS
+GARCON_MENU_PARSER_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>garcon-menu-tree-provider</FILE>
+GarconMenuTreeProvider
+GarconMenuTreeProviderIface
+garcon_menu_tree_provider_get_tree
+garcon_menu_tree_provider_get_file
+<SUBSECTION Standard>
+GARCON_MENU_TREE_PROVIDER
+GARCON_IS_MENU_TREE_PROVIDER
+GARCON_TYPE_MENU_TREE_PROVIDER
+garcon_menu_tree_provider_get_type
+GARCON_MENU_TREE_PROVIDER_GET_IFACE
+</SECTION>
+
+<SECTION>
+<FILE>garcon-menu-item-pool</FILE>
+GarconMenuItemPool
+garcon_menu_item_pool_new
+garcon_menu_item_pool_insert
+garcon_menu_item_pool_lookup
+garcon_menu_item_pool_foreach
+garcon_menu_item_pool_apply_exclude_rule
+garcon_menu_item_pool_get_empty
+<SUBSECTION Standard>
+GarconMenuItemPoolPrivate
+GarconMenuItemPoolClass
+GARCON_MENU_ITEM_POOL
+GARCON_IS_MENU_ITEM_POOL
+GARCON_TYPE_MENU_ITEM_POOL
+garcon_menu_item_pool_get_type
+GARCON_MENU_ITEM_POOL_CLASS
+GARCON_IS_MENU_ITEM_POOL_CLASS
+GARCON_MENU_ITEM_POOL_GET_CLASS
</SECTION>
<SECTION>
<FILE>garcon-menu-item</FILE>
-GarconMenuItemPrivate
-<TITLE>GarconMenuItem</TITLE>
GarconMenuItem
garcon_menu_item_new
garcon_menu_item_new_for_path
@@ -181,6 +248,8 @@ garcon_menu_item_get_allocated
garcon_menu_item_increment_allocated
garcon_menu_item_decrement_allocated
<SUBSECTION Standard>
+GarconMenuItemPrivate
+GarconMenuItemClass
GARCON_MENU_ITEM
GARCON_IS_MENU_ITEM
GARCON_TYPE_MENU_ITEM
@@ -191,46 +260,6 @@ GARCON_MENU_ITEM_GET_CLASS
</SECTION>
<SECTION>
-<FILE>garcon-menu-item-pool</FILE>
-GarconMenuItemPoolPrivate
-GarconMenuItemPoolClass
-GarconMenuItemPool
-garcon_menu_item_pool_new
-garcon_menu_item_pool_insert
-garcon_menu_item_pool_lookup
-garcon_menu_item_pool_foreach
-garcon_menu_item_pool_apply_exclude_rule
-garcon_menu_item_pool_get_empty
-<SUBSECTION Standard>
-GARCON_MENU_ITEM_POOL
-GARCON_IS_MENU_ITEM_POOL
-GARCON_TYPE_MENU_ITEM_POOL
-garcon_menu_item_pool_get_type
-GARCON_MENU_ITEM_POOL_CLASS
-GARCON_IS_MENU_ITEM_POOL_CLASS
-GARCON_MENU_ITEM_POOL_GET_CLASS
-</SECTION>
-
-<SECTION>
-<FILE>garcon-menu-item-cache</FILE>
-GarconMenuItemCachePrivate
-<TITLE>GarconMenuItemCache</TITLE>
-GarconMenuItemCache
-garcon_menu_item_cache_get_default
-garcon_menu_item_cache_lookup
-garcon_menu_item_cache_foreach
-garcon_menu_item_cache_invalidate
-<SUBSECTION Standard>
-GARCON_MENU_ITEM_CACHE
-GARCON_IS_MENU_ITEM_CACHE
-GARCON_TYPE_MENU_ITEM_CACHE
-garcon_menu_item_cache_get_type
-GARCON_MENU_ITEM_CACHE_CLASS
-GARCON_IS_MENU_ITEM_CACHE_CLASS
-GARCON_MENU_ITEM_CACHE_GET_CLASS
-</SECTION>
-
-<SECTION>
<FILE>garcon-menu-element</FILE>
GarconMenuElement
GarconMenuElementIface
@@ -249,32 +278,9 @@ GARCON_MENU_ELEMENT_GET_IFACE
</SECTION>
<SECTION>
-<FILE>garcon-menu-directory</FILE>
-GarconMenuDirectoryPrivate
-<TITLE>GarconMenuDirectory</TITLE>
-GarconMenuDirectory
-garcon_menu_directory_new
-garcon_menu_directory_get_file
-garcon_menu_directory_get_name
-garcon_menu_directory_set_name
-garcon_menu_directory_get_comment
-garcon_menu_directory_set_comment
-garcon_menu_directory_get_icon_name
-garcon_menu_directory_set_icon_name
-garcon_menu_directory_get_no_display
-garcon_menu_directory_set_no_display
-garcon_menu_directory_get_hidden
-garcon_menu_directory_get_show_in_environment
-garcon_menu_directory_get_visible
-garcon_menu_directory_equal
-<SUBSECTION Standard>
-GARCON_MENU_DIRECTORY
-GARCON_IS_MENU_DIRECTORY
-GARCON_TYPE_MENU_DIRECTORY
-garcon_menu_directory_get_type
-GARCON_MENU_DIRECTORY_CLASS
-GARCON_IS_MENU_DIRECTORY_CLASS
-GARCON_MENU_DIRECTORY_GET_CLASS
+<FILE>garcon-environment</FILE>
+garcon_set_environment
+garcon_get_environment
</SECTION>
<SECTION>
@@ -290,18 +296,3 @@ garcon_check_version
garcon_config_lookup
</SECTION>
-<SECTION>
-<FILE>garcon</FILE>
-GARCON_INSIDE_GARCON_H
-</SECTION>
-
-<SECTION>
-<FILE>garcon-private</FILE>
-</SECTION>
-
-<SECTION>
-<FILE>garcon-environment</FILE>
-garcon_set_environment
-garcon_get_environment
-</SECTION>
-
diff --git a/garcon/garcon-config.c b/garcon/garcon-config.c
index 3669262..56fef3d 100644
--- a/garcon/garcon-config.c
+++ b/garcon/garcon-config.c
@@ -26,8 +26,55 @@
+/**
+ * SECTION: garcon-config
+ * @title: Version Information
+ * @short_description: Information about the garcon version in use.
+ * @include: garcon/garcon.h
+ *
+ * The garcon library provides version information, which could be used
+ * by developers to handle new API.
+ **/
+
+
+
+/**
+ * garcon_major_version:
+ *
+ * The major version number of the garcon library (e.g. in
+ * version 4.8.0 this is 4).
+ *
+ * This variable is in the library, so represents the
+ * garcon library you have linked against. Contrast with the
+ * #GARCON_MAJOR_VERSION macro, which represents the major
+ * version of the garcon headers you have included.
+ **/
const guint garcon_major_version = GARCON_MAJOR_VERSION;
+
+/**
+ * garcon_minor_version:
+ *
+ * The minor version number of the garcon library (e.g. in
+ * version 4.8.0 this is 8).
+ *
+ * This variable is in the library, so represents the
+ * garcon library you have linked against. Contrast with the
+ * #GARCON_MINOR_VERSION macro, which represents the minor
+ * version of the garcon headers you have included.
+ **/
const guint garcon_minor_version = GARCON_MINOR_VERSION;
+
+/**
+ * garcon_micro_version:
+ *
+ * The micro version number of the garcon library (e.g. in
+ * version 4.8.0 this is 0).
+ *
+ * This variable is in the library, so represents the
+ * garcon library you have linked against. Contrast with the
+ * #GARCON_MICRO_VERSION macro, which represents the micro
+ * version of the garcon headers you have included.
+ **/
const guint garcon_micro_version = GARCON_MICRO_VERSION;
@@ -60,12 +107,10 @@ const guint garcon_micro_version = GARCON_MICRO_VERSION;
* </programlisting>
* </example>
*
- * Return value: %NULL if the library is compatible with the given version,
- * or a string describing the version mismatch. The returned
- * string is owned by the library and must not be freed or
- * modified by the caller.
- *
- * Since: 0.3.1
+ * Returns: %NULL if the library is compatible with the given version,
+ * or a string describing the version mismatch. The returned
+ * string is owned by the library and must not be freed or
+ * modified by the caller.
**/
const gchar*
garcon_check_version (guint required_major,
@@ -77,6 +122,17 @@ garcon_check_version (guint required_major,
+/**
+ * garcon_config_lookup:
+ * @filename : relative filename of the config resource.
+ *
+ * Looks for the filename in the users' config directory and then
+ * the system config directories.
+ *
+ * Returns: the absolute path to the first file in the search path,
+ * that matches @filename or %NULL if no such
+ * file or directory could be found.
+ **/
gchar *
garcon_config_lookup (const gchar *filename)
{
diff --git a/garcon/garcon-config.h.in b/garcon/garcon-config.h.in
index 613a137..baae3b8 100644
--- a/garcon/garcon-config.h.in
+++ b/garcon/garcon-config.h.in
@@ -30,10 +30,47 @@
G_BEGIN_DECLS
+/**
+ * GARCON_MAJOR_VERSION:
+ *
+ * The major version number of the garcon library.
+ * Like garcon_major_version, but from the headers used at
+ * application compile time, rather than from the library
+ * linked against at application run time.
+ **/
#define GARCON_MAJOR_VERSION @GARCON_VERSION_MAJOR@
+
+/**
+ * GARCON_MINOR_VERSION:
+ *
+ * The minor version number of the garcon library.
+ * Like garcon_minor_version, but from the headers used at
+ * application compile time, rather than from the library
+ * linked against at application run time.
+ **/
#define GARCON_MINOR_VERSION @GARCON_VERSION_MINOR@
+
+/**
+ * GARCON_MICRO_VERSION:
+ *
+ * The micro version number of the garcon library.
+ * Like garcon_micro_version, but from the headers used at
+ * application compile time, rather than from the library
+ * linked against at application run time.
+ **/
#define GARCON_MICRO_VERSION @GARCON_VERSION_MICRO@
+/**
+ * GARCON_CHECK_VERSION:
+ * @major : the major version number.
+ * @minor : the minor version number.
+ * @micro : the micro version number.
+ *
+ * Checks the version of the garcon library.
+ *
+ * Returns: %TRUE if the version of the garcon header files is
+ * the same as or newer than the passed-in version.
+ **/
#define GARCON_CHECK_VERSION(major,minor,micro) \
(GARCON_MAJOR_VERSION > (major) \
|| (GARCON_MAJOR_VERSION == (major) \
diff --git a/garcon/garcon-environment.c b/garcon/garcon-environment.c
index 690b6be..f6160cd 100644
--- a/garcon/garcon-environment.c
+++ b/garcon/garcon-environment.c
@@ -26,12 +26,14 @@
#include <garcon/garcon-environment.h>
-
/**
- * SECTION:garcon-menu-environment
+ * SECTION: garcon-environment
* @title: Desktop Environment Configuration
+ * @short_description: Desktop Environment Configuration
+ * @include: garcon/garcon.h
*
- * Desktop Environment Configuration
+ * Set the desktop environment used by the OnlyShowIn and NotShowIn
+ * desktop files keys.
**/
@@ -63,8 +65,10 @@ garcon_set_environment (const gchar *env)
/**
* garcon_get_environment:
*
- * Return value: Name of the desktop environment (e.g. XFCE, KDE, GNOME)
- * which is used or %NULL.
+ * Get the environment set with garcon_set_environment().
+ *
+ * Returns: Name of the desktop environment (e.g. XFCE, KDE, GNOME)
+ * which is used or %NULL.
*/
const gchar *
garcon_get_environment (void)
diff --git a/garcon/garcon-menu-directory.c b/garcon/garcon-menu-directory.c
index a20647c..1203059 100644
--- a/garcon/garcon-menu-directory.c
+++ b/garcon/garcon-menu-directory.c
@@ -30,6 +30,19 @@
+/**
+ * SECTION: garcon-menu-directory
+ * @title: GarconMenuDirectory
+ * @short_description: Garcon element for .directory files.
+ * @include: garcon/garcon.h
+ *
+ * Element that represents a .directory file in the menu configurations.
+ * Each menu (except for the root menu) has a #GarconMenuDirectory,
+ * see garcon_menu_get_directory().
+ **/
+
+
+
#define GARCON_MENU_DIRECTORY_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), GARCON_TYPE_MENU_DIRECTORY, GarconMenuDirectoryPrivate))
@@ -106,6 +119,7 @@ struct _GarconMenuDirectoryPrivate
+/* TODO, maybe implement the GarconMenuElement interface */
G_DEFINE_TYPE (GarconMenuDirectory, garcon_menu_directory, G_TYPE_OBJECT)
@@ -314,6 +328,15 @@ garcon_menu_directory_set_property (GObject *object,
+/**
+ * garcon_menu_directory_new:
+ * @file : a #GFile
+ *
+ * Create a new #GarconMenuDirectory for @file. You most likely never
+ * use this, but retrieve the info from garcon_menu_get_directory().
+ *
+ * Returns: a #GarconMenuDirectory.
+ **/
GarconMenuDirectory *
garcon_menu_directory_new (GFile *file)
{
@@ -386,10 +409,11 @@ garcon_menu_directory_new (GFile *file)
/**
* garcon_menu_directory_get_file:
+ * @directory : a #GarconMenuDirectory
*
* Get the file for @directory.
*
- * Return value: a #GFile. The returned object
+ * Returns: a #GFile. The returned object
* should be unreffed with g_object_unref() when no longer needed.
*/
GFile *
@@ -401,6 +425,14 @@ garcon_menu_directory_get_file (GarconMenuDirectory *directory)
+/**
+ * garcon_menu_directory_get_name:
+ * @directory : a #GarconMenuDirectory
+ *
+ * Get the name of @directory.
+ *
+ * Returns: a the name for @directory.
+ */
const gchar*
garcon_menu_directory_get_name (GarconMenuDirectory *directory)
{
@@ -410,6 +442,13 @@ garcon_menu_directory_get_name (GarconMenuDirectory *directory)
+/**
+ * garcon_menu_directory_set_name:
+ * @directory : a #GarconMenuDirectory
+ * @name : the new name for @directory.
+ *
+ * Set the name of @directory.
+ */
void
garcon_menu_directory_set_name (GarconMenuDirectory *directory,
const gchar *name)
@@ -430,6 +469,14 @@ garcon_menu_directory_set_name (GarconMenuDirectory *directory,
+/**
+ * garcon_menu_directory_get_comment:
+ * @directory : a #GarconMenuDirectory
+ *
+ * Get the comment of @directory.
+ *
+ * Returns: a the description for @directory.
+ */
const gchar*
garcon_menu_directory_get_comment (GarconMenuDirectory *directory)
{
@@ -439,6 +486,13 @@ garcon_menu_directory_get_comment (GarconMenuDirectory *directory)
+/**
+ * garcon_menu_directory_set_comment:
+ * @directory : a #GarconMenuDirectory
+ * @comment : the new description for @directory.
+ *
+ * Set the comment of @directory.
+ */
void
garcon_menu_directory_set_comment (GarconMenuDirectory *directory,
const gchar *comment)
@@ -457,6 +511,15 @@ garcon_menu_directory_set_comment (GarconMenuDirectory *directory,
}
+
+/**
+ * garcon_menu_directory_get_icon_name:
+ * @directory : a #GarconMenuDirectory
+ *
+ * Get the icon name of @directory.
+ *
+ * Returns: a the icon-name key for @directory.
+ */
const gchar*
garcon_menu_directory_get_icon_name (GarconMenuDirectory *directory)
{
@@ -466,6 +529,13 @@ 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.
+ *
+ * Set the icon name of @directory.
+ */
void
garcon_menu_directory_set_icon_name (GarconMenuDirectory *directory,
const gchar *icon_name)
@@ -485,6 +555,15 @@ garcon_menu_directory_set_icon_name (GarconMenuDirectory *directory,
+/**
+ * garcon_menu_directory_get_no_display:
+ * @directory : a #GarconMenuDirectory
+ *
+ * Whether @directory should be displayed.
+ * For applications you want to call garcon_menu_directory_get_visible().
+ *
+ * Returns: a the no-display key for @directory.
+ */
gboolean
garcon_menu_directory_get_no_display (GarconMenuDirectory *directory)
{
@@ -494,6 +573,13 @@ garcon_menu_directory_get_no_display (GarconMenuDirectory *directory)
+/**
+ * garcon_menu_directory_set_no_display:
+ * @directory : a #GarconMenuDirectory
+ * @no_display : whether @directory should be displayed.
+ *
+ * Set the NoDisplay key of @directory.
+ */
void
garcon_menu_directory_set_no_display (GarconMenuDirectory *directory,
gboolean no_display)
@@ -513,6 +599,15 @@ garcon_menu_directory_set_no_display (GarconMenuDirectory *directory,
+/**
+ * garcon_menu_directory_get_hidden:
+ * @directory : a #GarconMenuDirectory
+ *
+ * Whether @directory should be hidden.
+ * For applications you want to call garcon_menu_directory_get_visible().
+ *
+ * Returns: a the hidden key for @directory.
+ */
gboolean
garcon_menu_directory_get_hidden (GarconMenuDirectory *directory)
{
@@ -522,6 +617,16 @@ garcon_menu_directory_get_hidden (GarconMenuDirectory *directory)
+/**
+ * garcon_menu_directory_get_show_in_environment:
+ * @directory : a #GarconMenuDirectory
+ *
+ * Whether @directory is visible in the current environment
+ * which has been set by garcon_set_environment().
+ * For applications you want to call garcon_menu_directory_get_visible().
+ *
+ * Returns: %TRUE is visible in environment, else %FALSE.
+ */
gboolean
garcon_menu_directory_get_show_in_environment (GarconMenuDirectory *directory)
{
@@ -560,6 +665,17 @@ garcon_menu_directory_get_show_in_environment (GarconMenuDirectory *directory)
+/**
+ * garcon_menu_directory_get_visible:
+ * @directory : a #GarconMenuDirectory
+ *
+ * Check which runs the following checks:
+ * garcon_menu_directory_get_show_in_environment(),
+ * garcon_menu_directory_get_hidden() and
+ * garcon_menu_directory_get_no_display().
+ *
+ * Returns: if visible %TRUE, else %FALSE.
+ **/
gboolean
garcon_menu_directory_get_visible (GarconMenuDirectory *directory)
{
@@ -576,7 +692,15 @@ garcon_menu_directory_get_visible (GarconMenuDirectory *directory)
}
-
+/**
+ * garcon_menu_directory_equal:
+ * @directory : a #GarconMenuDirectory
+ * @other : a #GarconMenuDirectory
+ *
+ * Checks if both directories point to the same file.
+ *
+ * Returns: if files are equal %TRUE, else %FALSE.
+ **/
gboolean
garcon_menu_directory_equal (GarconMenuDirectory *directory,
GarconMenuDirectory *other)
diff --git a/garcon/garcon-menu-element.c b/garcon/garcon-menu-element.c
index 84eea95..5978120 100644
--- a/garcon/garcon-menu-element.c
+++ b/garcon/garcon-menu-element.c
@@ -26,6 +26,18 @@
+/**
+ * SECTION: garcon-menu-element
+ * @title: GarconMenuElement
+ * @short_description: Central interface.
+ * @include: garcon/garcon.h
+ *
+ * Interface implemented by the Garcon types #GarconMenuItem, #GarconMenuSeparator
+ * and #GarconMenu.
+ **/
+
+
+
GType
garcon_menu_element_get_type (void)
{
diff --git a/garcon/garcon-menu.c b/garcon/garcon-menu.c
index 19b66ca..6634a33 100644
--- a/garcon/garcon-menu.c
+++ b/garcon/garcon-menu.c
@@ -52,8 +52,12 @@
/**
- * SECTION:garcon
+ * SECTION: garcon-menu
* @title: GarconMenu
+ * @short_description: Menu element.
+ * @include: garcon/garcon.h
+ *
+ * Main element the contains the parsed menu.
**/
@@ -338,7 +342,7 @@ garcon_menu_set_property (GObject *object,
*
* For more information about the usage @see garcon_menu_new().
*
- * Return value: a new #GarconMenu for @file.
+ * Returns: a new #GarconMenu for @file.
**/
GarconMenu *
garcon_menu_new (GFile *file)
@@ -372,7 +376,7 @@ garcon_menu_new (GFile *file)
* The caller is responsible to destroy the returned #GarconMenu
* using g_object_unref().
*
- * Return value: a new #GarconMenu for @filename.
+ * Returns: a new #GarconMenu for @filename.
**/
GarconMenu *
garcon_menu_new_for_path (const gchar *filename)
@@ -400,7 +404,7 @@ garcon_menu_new_for_path (const gchar *filename)
*
* For more information about the usage @see garcon_menu_new().
*
- * Return value: a new #GarconMenu for applications.menu.
+ * Returns: a new #GarconMenu for applications.menu.
**/
GarconMenu *
garcon_menu_new_applications (void)
@@ -439,8 +443,8 @@ garcon_menu_new_applications (void)
* Get the file for @menu. It refers to the .menu file from which
* @menu was or will be loaded.
*
- * Return value: a #GFile. 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.
*/
GFile *
garcon_menu_get_file (GarconMenu *menu)
@@ -451,6 +455,7 @@ garcon_menu_get_file (GarconMenu *menu)
+
static const gchar *
garcon_menu_get_name (GarconMenu *menu)
{
@@ -471,9 +476,9 @@ garcon_menu_get_name (GarconMenu *menu)
* the menu like the display and icon name, desktop environments it
* should show up in etc.
*
- * Return value: #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: #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.
*/
GarconMenuDirectory*
garcon_menu_get_directory (GarconMenu *menu)
@@ -529,9 +534,9 @@ garcon_menu_set_directory (GarconMenu *menu,
* @error should either be NULL or point to a #GError return location
* where errors should be stored in.
*
- * Return value: %TRUE if the menu was loaded successfully or
- * %FALSE if there was an error or the process was
- * cancelled.
+ * Returns: %TRUE if the menu was loaded successfully or
+ * %FALSE if there was an error or the process was
+ * cancelled.
**/
gboolean
garcon_menu_load (GarconMenu *menu,
@@ -590,6 +595,15 @@ garcon_menu_load (GarconMenu *menu,
+/**
+ * garcon_menu_get_menus:
+ * @menu : a #GarconMenu
+ *
+ * Returns a sorted list of #GarconMenu submenus of @menu.
+ *
+ * Returns: a sorted list of #GarconMenu object. The list should
+ * be freed with g_list_free().
+ **/
GList *
garcon_menu_get_menus (GarconMenu *menu)
{
@@ -608,6 +622,13 @@ garcon_menu_get_menus (GarconMenu *menu)
+/**
+ * garcon_menu_add_menu:
+ * @menu : a #GarconMenu
+ * @submenu : a #GarconMenu
+ *
+ * Adds @submenu as a sub menu to @menu.
+ **/
void
garcon_menu_add_menu (GarconMenu *menu,
GarconMenu *submenu)
@@ -627,6 +648,15 @@ garcon_menu_add_menu (GarconMenu *menu,
+/**
+ * garcon_menu_get_menu_with_name:
+ * @menu : a #GarconMenu
+ * @name : a sub menu name
+ *
+ * Looks in @menu for a submenu with @name as name.
+ *
+ * Returns: a #GarconMenu or %NULL.
+ **/
GarconMenu *
garcon_menu_get_menu_with_name (GarconMenu *menu,
const gchar *name)
@@ -650,6 +680,14 @@ garcon_menu_get_menu_with_name (GarconMenu *menu,
+/**
+ * garcon_menu_get_parent:
+ * @menu : a #GarconMenu
+ *
+ * Returns the parent #GarconMenu or @menu.
+ *
+ * Returns: a #GarconMenu or %NULL if @menu is the root menu.
+ **/
GarconMenu *
garcon_menu_get_parent (GarconMenu *menu)
{
@@ -1120,7 +1158,15 @@ garcon_menu_remove_deleted_menus (GarconMenu *menu)
}
-
+/**
+ * garcon_menu_get_item_pool:
+ * @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.
+ **/
GarconMenuItemPool*
garcon_menu_get_item_pool (GarconMenu *menu)
{
@@ -1154,7 +1200,7 @@ items_collect (const gchar *desktop_id,
* </programlisting></informalexample>
* when no longer needed.
*
- * Return value: list of #GarconMenuItem<!---->s included in @menu.
+ * Returns: list of #GarconMenuItem<!---->s included in @menu.
**/
GList *
garcon_menu_get_items (GarconMenu *menu)
@@ -1272,6 +1318,16 @@ layout_elements_collect (GList **dest_list,
+/**
+ * garcon_menu_get_elements:
+ * @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().
+ **/
GList *
garcon_menu_get_elements (GarconMenu *menu)
{
More information about the Xfce4-commits
mailing list