[nautilus-actions] Reference manual: Fix Miscellaneous Utilities documentation

From: Pierre Wieser <pwieser src gnome org>
To: commits-list gnome org
Cc:
Subject: [nautilus-actions] Reference manual: Fix Miscellaneous Utilities documentation
Date: Sun, 12 Dec 2010 00:24:07 +0000 (UTC)
commit 1251697a44fbfe6bd3206edabc31756ec7b4ddf4
Author: Pierre Wieser <pwieser trychlos org>
Date:   Sun Dec 12 01:25:02 2010 +0100

    Reference manual: Fix Miscellaneous Utilities documentation

 ChangeLog                                    |   11 +++
 docs/reference/nautilus-actions-docs.xml     |    2 +-
 docs/reference/nautilus-actions-sections.txt |   19 ++++--
 src/api/na-core-utils.h                      |    3 +-
 src/api/na-gconf-monitor.h                   |   21 +++---
 src/api/na-gconf-utils.h                     |    5 +-
 src/core/na-core-utils.c                     |   94 +++++++++++++++++++++++--
 src/core/na-gconf-monitor.c                  |   12 ++-
 src/core/na-gconf-utils.c                    |   72 +++++++++++++++-----
 9 files changed, 192 insertions(+), 47 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index be94886..a84ac3f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,16 @@
 2010-12-11 Pierre Wieser <pwieser trychlos org>
 
+	Fic Miscellaneous API documentation.
+
+	* docs/reference/nautilus-actions-docs.xml:
+	* docs/reference/nautilus-actions-sections.txt:
+	* src/api/na-core-utils.h:
+	* src/api/na-gconf-monitor.h:
+	* src/api/na-gconf-utils.h:
+	* src/core/na-core-utils.c:
+	* src/core/na-gconf-monitor.c:
+	* src/core/na-gconf-utils.c: Updated accordingly.
+
 	Fix NAObject API documentation.
 
 	* docs/reference/nautilus-actions-docs.xml:
diff --git a/docs/reference/nautilus-actions-docs.xml b/docs/reference/nautilus-actions-docs.xml
index 4f552af..7347ad1 100644
--- a/docs/reference/nautilus-actions-docs.xml
+++ b/docs/reference/nautilus-actions-docs.xml
@@ -82,9 +82,9 @@
 
   <chapter>
     <title>Miscellaneous API</title>
-    <xi:include href="xml/core-utils.xml"/>
     <xi:include href="xml/gconf-monitor.xml"/>
     <xi:include href="xml/gconf-utils.xml"/>
+    <xi:include href="xml/core-utils.xml"/>
   </chapter>
 
   <chapter id="object-tree">
diff --git a/docs/reference/nautilus-actions-sections.txt b/docs/reference/nautilus-actions-sections.txt
index 5a49478..88d503d 100644
--- a/docs/reference/nautilus-actions-sections.txt
+++ b/docs/reference/nautilus-actions-sections.txt
@@ -628,30 +628,34 @@ na_object_set_capabilities
 </SECTION>
 
 # ---------------------------------------------------------------------
+# NAGConfMonitor â?? The GConf Monitoring Class Definition
 
 <SECTION>
 <FILE>gconf-monitor</FILE>
-<TITLE>NAGConfMonitor</TITLE>
 NA_GCONF_MONITOR_TYPE
-NAGConfMonitorPrivate
-NAGConfMonitorClassPrivate
+NA_GCONF_MONITOR
+NA_IS_GCONF_MONITOR
 NAGConfMonitor
 na_gconf_monitor_new
 na_gconf_monitor_release_monitors
 
 <SUBSECTION Standard>
-NA_GCONF_MONITOR
-NA_IS_GCONF_MONITOR
 na_gconf_monitor_get_type
 NA_GCONF_MONITOR_CLASS
 NA_IS_GCONF_MONITOR_CLASS
 NA_GCONF_MONITOR_GET_CLASS
+NAGConfMonitorClass
+
+<SUBSECTION Private>
+NAGConfMonitorPrivate
+NAGConfMonitorClassPrivate
 </SECTION>
 
 # ---------------------------------------------------------------------
+# GConf Misc â?? The Library Utilities 
 
 <SECTION>
-<FILE>na-gconf-utils</FILE>
+<FILE>gconf-utils</FILE>
 na_gconf_utils_get_subdirs
 na_gconf_utils_free_subdirs
 na_gconf_utils_has_entry
@@ -674,6 +678,9 @@ na_gconf_utils_slist_from_string
 na_gconf_utils_slist_to_string
 </SECTION>
 
+# ---------------------------------------------------------------------
+# Core Misc â?? The Library Utilities 
+
 <SECTION>
 <FILE>core-utils</FILE>
 na_core_utils_boolean_from_string
diff --git a/src/api/na-core-utils.h b/src/api/na-core-utils.h
index 2fc34c2..7f33104 100644
--- a/src/api/na-core-utils.h
+++ b/src/api/na-core-utils.h
@@ -33,7 +33,8 @@
 
 /**
  * SECTION: core-utils
- * @short_description: Core library utilities.
+ * @title: Core Misc
+ * @short_description: The Library Utilities
  * @include: nautilus-action/na-core-utils.h
  */
 
diff --git a/src/api/na-gconf-monitor.h b/src/api/na-gconf-monitor.h
index 7ca5c17..5acad86 100644
--- a/src/api/na-gconf-monitor.h
+++ b/src/api/na-gconf-monitor.h
@@ -33,7 +33,8 @@
 
 /**
  * SECTION: gconf-monitor
- * @short_description: #NAGConfMonitor class definition.
+ * @title: NAGConfMonitor
+ * @short_description: The GConf Monitoring Class Definition
  * @include: nautilus-actions/na-gconf-monitor.h
  *
  * This class manages the GConf monitoring.
@@ -45,24 +46,26 @@
 
 G_BEGIN_DECLS
 
-#define NA_GCONF_MONITOR_TYPE					( na_gconf_monitor_get_type())
-#define NA_GCONF_MONITOR( object )				( G_TYPE_CHECK_INSTANCE_CAST( object, NA_GCONF_MONITOR_TYPE, NAGConfMonitor ))
-#define NA_GCONF_MONITOR_CLASS( klass )			( G_TYPE_CHECK_CLASS_CAST( klass, NA_GCONF_MONITOR_TYPE, NAGConfMonitorClass ))
-#define NA_IS_GCONF_MONITOR( object )			( G_TYPE_CHECK_INSTANCE_TYPE( object, NA_GCONF_MONITOR_TYPE ))
-#define NA_IS_GCONF_MONITOR_CLASS( klass )		( G_TYPE_CHECK_CLASS_TYPE(( klass ), NA_GCONF_MONITOR_TYPE ))
-#define NA_GCONF_MONITOR_GET_CLASS( object )	( G_TYPE_INSTANCE_GET_CLASS(( object ), NA_GCONF_MONITOR_TYPE, NAGConfMonitorClass ))
+#define NA_GCONF_MONITOR_TYPE                  ( na_gconf_monitor_get_type())
+#define NA_GCONF_MONITOR( object )             ( G_TYPE_CHECK_INSTANCE_CAST( object, NA_GCONF_MONITOR_TYPE, NAGConfMonitor ))
+#define NA_GCONF_MONITOR_CLASS( klass )        ( G_TYPE_CHECK_CLASS_CAST( klass, NA_GCONF_MONITOR_TYPE, NAGConfMonitorClass ))
+#define NA_IS_GCONF_MONITOR( object )          ( G_TYPE_CHECK_INSTANCE_TYPE( object, NA_GCONF_MONITOR_TYPE ))
+#define NA_IS_GCONF_MONITOR_CLASS( klass )     ( G_TYPE_CHECK_CLASS_TYPE(( klass ), NA_GCONF_MONITOR_TYPE ))
+#define NA_GCONF_MONITOR_GET_CLASS( object )   ( G_TYPE_INSTANCE_GET_CLASS(( object ), NA_GCONF_MONITOR_TYPE, NAGConfMonitorClass ))
 
-typedef struct NAGConfMonitorPrivate NAGConfMonitorPrivate;
+typedef struct _NAGConfMonitorPrivate NAGConfMonitorPrivate;
 
 typedef struct {
+	/*< private >*/
 	GObject                parent;
 	NAGConfMonitorPrivate *private;
 }
 	NAGConfMonitor;
 
-typedef struct NAGConfMonitorClassPrivate NAGConfMonitorClassPrivate;
+typedef struct _NAGConfMonitorClassPrivate NAGConfMonitorClassPrivate;
 
 typedef struct {
+	/*< private >*/
 	GObjectClass                parent;
 	NAGConfMonitorClassPrivate *private;
 }
diff --git a/src/api/na-gconf-utils.h b/src/api/na-gconf-utils.h
index aa1a216..7b5d642 100644
--- a/src/api/na-gconf-utils.h
+++ b/src/api/na-gconf-utils.h
@@ -32,8 +32,9 @@
 #define __NAUTILUS_ACTIONS_API_NA_GCONF_UTILS_H__
 
 /**
- * SECTION: na_gconf_utils
- * @short_description: GConf utilities.
+ * SECTION: gconf-utils
+ * @title: GConf Misc
+ * @short_description: The Library Utilities
  * @include: runtime/na-gconf-utils.h
  */
 
diff --git a/src/core/na-core-utils.c b/src/core/na-core-utils.c
index 58fb3e5..0792fbc 100644
--- a/src/core/na-core-utils.c
+++ b/src/core/na-core-utils.c
@@ -52,6 +52,8 @@ static gboolean info_dir_is_writable( GFile *file, const gchar *path );
  *
  * Returns: %TRUE if the string evaluates to "true" (case insensitive),
  * %FALSE else.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gboolean
 na_core_utils_boolean_from_string( const gchar *string )
@@ -67,6 +69,8 @@ na_core_utils_boolean_from_string( const gchar *string )
  * Appends a prefix to each line of the string.
  *
  * Returns: a new string which should be g_free() by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gchar *
 na_core_utils_str_add_prefix( const gchar *prefix, const gchar *str )
@@ -91,7 +95,20 @@ na_core_utils_str_add_prefix( const gchar *prefix, const gchar *str )
  * @str1: an UTF-8 encoded string.
  * @str2: an UTF-8 encoded string.
  *
- * Returns: -1 if str1 < str2, 0 if str1 = str2, +1 if str1 > str2.
+ * Returns:
+ * <itemizedlist>
+ *   <listitem>
+ *     <para>-1 if str1 < str2,</para>
+ *   </listitem>
+ *   <listitem>
+ *     <para>0 if str1 = str2,</para>
+ *   </listitem>
+ *   <listitem>
+ *     <para>+1 if str1 > str2.</para>
+ *   </listitem>
+ * </itemizedlist>
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 int
 na_core_utils_str_collate( const gchar *str1, const gchar *str2 )
@@ -120,6 +137,8 @@ na_core_utils_str_collate( const gchar *str1, const gchar *str2 )
  * minus all the found occurrences of the given @to_remove char.
  *
  * The returned string should be g_free() by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gchar *
 na_core_utils_str_remove_char( const gchar *string, const gchar *to_remove )
@@ -162,6 +181,8 @@ na_core_utils_str_remove_char( const gchar *string, const gchar *to_remove )
  * @suffix, then the returned string is equal to source @string.
  *
  * The returned string should be g_free() by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gchar *
 na_core_utils_str_remove_suffix( const gchar *string, const gchar *suffix )
@@ -186,10 +207,18 @@ na_core_utils_str_remove_suffix( const gchar *string, const gchar *suffix )
  * @other: a pointer to a gchar *.
  *
  * Split the @string string into two components:
- * - the first word which is allocated in @first,
- * - the rest of the string which is allocated in @other.
+ * <itemizedlist>
+ *   <listitem>
+ *     <para>the first word which is allocated in @first,</para>
+ *   </listitem>
+ *   <listitem>
+ *     <para>the rest of the string which is allocated in @other.</para>
+ *   </listitem>
+ * </itemizedlist>
  *
  * The two allocated strings should be g_free() by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_core_utils_str_split_first_word( const gchar *string, gchar **first, gchar **other )
@@ -238,6 +267,8 @@ na_core_utils_slist_add_message( GSList **messages, const gchar *format, ... )
  * Returns: a #GSList of strings.
  *
  * The returned list should be na_core_utils_slist_free() by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 GSList *
 na_core_utils_slist_duplicate( GSList *slist )
@@ -261,6 +292,8 @@ na_core_utils_slist_duplicate( GSList *slist )
  * @list: a list of strings.
  *
  * Dumps the content of a list of strings.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_core_utils_slist_dump( const gchar *prefix, GSList *list )
@@ -287,6 +320,8 @@ na_core_utils_slist_dump( const gchar *prefix, GSList *list )
  * Returns: a #GSList with the list of strings after having been splitted.
  *
  * The returned #GSList should be na_core_utils_slist_free() by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 GSList *
 na_core_utils_slist_from_split( const gchar *text, const gchar *separator )
@@ -321,6 +356,8 @@ na_core_utils_slist_from_split( const gchar *text, const gchar *separator )
  *
  * Returns: a #GSList list of strings, which should be #na_core_utils_slist_free()
  * by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 GSList *
 na_core_utils_slist_from_array( const gchar **str_array )
@@ -345,6 +382,8 @@ na_core_utils_slist_from_array( const gchar **str_array )
  * @link: the string used to join each element.
  *
  * Returns: a newly allocated string which should be g_free() by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gchar *
 na_core_utils_slist_join_at_end( GSList *slist, const gchar *link )
@@ -372,6 +411,8 @@ na_core_utils_slist_join_at_end( GSList *slist, const gchar *link )
  * Removes a string from a GSList of strings.
  *
  * Returns: the same, updated, @slist.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 GSList *
 na_core_utils_slist_remove_ascii( GSList *slist, const gchar *text )
@@ -400,6 +441,8 @@ na_core_utils_slist_remove_ascii( GSList *slist, const gchar *text )
  * @text.
  *
  * Returns: the new @slist start position.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 GSList *
 na_core_utils_slist_remove_utf8( GSList *slist, const gchar *text )
@@ -424,6 +467,8 @@ na_core_utils_slist_remove_utf8( GSList *slist, const gchar *text )
  *
  * Returns: a newly allocated array of strings, which should be
  * g_strfreev() by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gchar **
 na_core_utils_slist_to_array( GSList *slist )
@@ -451,6 +496,8 @@ na_core_utils_slist_to_array( GSList *slist )
  *
  * Returns: a newly allocated string, which should be g_free() by the
  * caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gchar *
 na_core_utils_slist_to_text( GSList *slist )
@@ -483,6 +530,8 @@ na_core_utils_slist_to_text( GSList *slist )
  * or not if @set is %FALSE.
  *
  * Returns: the updated @list.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 GSList *
 na_core_utils_slist_setup_element( GSList *list, const gchar *element, gboolean set )
@@ -509,6 +558,8 @@ na_core_utils_slist_setup_element( GSList *list, const gchar *element, gboolean
  * Search for a string in a string list.
  *
  * Returns: the count of @Ã?tr in @list list.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 guint
 na_core_utils_slist_count( GSList *list, const gchar *str )
@@ -536,6 +587,8 @@ na_core_utils_slist_count( GSList *list, const gchar *str )
  * Search for a string in a string list which may contain nagated items.
  *
  * Returns: %TRUE if the string has been found in list.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gboolean
 na_core_utils_slist_find_negated( GSList *list, const gchar *str )
@@ -569,6 +622,8 @@ na_core_utils_slist_find_negated( GSList *list, const gchar *str )
  * Compare two string lists, without regards to the order.
  *
  * Returns: %TRUE if the two lists have same content.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gboolean
 na_core_utils_slist_are_equal( GSList *a, GSList *b )
@@ -597,6 +652,8 @@ na_core_utils_slist_are_equal( GSList *a, GSList *b )
  * @slist: a #GSList list of strings.
  *
  * Releases the strings and the list itself.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_core_utils_slist_free( GSList *slist )
@@ -614,6 +671,8 @@ na_core_utils_slist_free( GSList *slist )
  * Concatenates a gchar **list of strings to a new string.
  *
  * Returns: a newly allocated string which should be g_free() by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gchar *
 na_core_utils_gstring_joinv( const gchar *start, const gchar *separator, gchar **list )
@@ -678,6 +737,8 @@ text_to_string_list( const gchar *text, const gchar *separator, const gchar *def
  * relevant integer.
  *
  * The two returned strings must be g_free() by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_core_utils_selcount_get_ope_int( const gchar *selcount, gchar **ope, gchar **uint )
@@ -713,6 +774,8 @@ na_core_utils_selcount_get_ope_int( const gchar *selcount, gchar **ope, gchar **
  * but before the caller has been able to actually write into it.
  *
  * There is no "super-test". Just try...
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gboolean
 na_core_utils_dir_is_writable_path( const gchar *path )
@@ -744,6 +807,8 @@ na_core_utils_dir_is_writable_path( const gchar *path )
  * but before the caller has been able to actually write into it.
  *
  * There is no "super-test". Just try...
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gboolean
 na_core_utils_dir_is_writable_uri( const gchar *uri )
@@ -812,6 +877,8 @@ info_dir_is_writable( GFile *file, const gchar *path_or_uri )
  * allocated buffers which should be g_free() by the caller.
  *
  * The extension is set to an empty string if no extension is detected.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_core_utils_dir_split_ext( const gchar *string, gchar **first, gchar **ext )
@@ -849,6 +916,8 @@ na_core_utils_dir_split_ext( const gchar *string, gchar **first, gchar **ext )
  * @path: the path of the file to be deleted.
  *
  * Returns: %TRUE if the file is successfully deleted, %FALSE else.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gboolean
 na_core_utils_file_delete( const gchar *path )
@@ -876,7 +945,10 @@ na_core_utils_file_delete( const gchar *path )
  *
  * Returns: %TRUE if the specified file exists, %FALSE else.
  *
- * Race condition: cf. na_core_utils_dir_is_writable() comment.
+ * Race condition: cf. na_core_utils_dir_is_writable_path() and
+ * na_core_utils_dir_is_writable_uri() comments.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gboolean
 na_core_utils_file_exists( const gchar *uri )
@@ -901,6 +973,8 @@ na_core_utils_file_exists( const gchar *uri )
  *
  * Returns: the newly allocated buffer which contains the file content, or %NULL.
  * This buffer should be g_free() by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gchar *
 na_core_utils_file_load_from_uri( const gchar *uri, gsize *length )
@@ -928,10 +1002,14 @@ na_core_utils_file_load_from_uri( const gchar *uri, gsize *length )
  *
  * Print a version message on the console
  *
- * nautilus-actions-new (Nautilus-Actions) v 2.29.1
- * Copyright (C) 2005-2007 Frederic Ruaudel
- * Copyright (C) 2009, 2010 Pierre Wieser
- * Nautilus-Actions is free software, licensed under GPLv2 or later.
+ * <programlisting>
+ *   nautilus-actions-new (Nautilus-Actions) v 2.29.1
+ *   Copyright (C) 2005-2007 Frederic Ruaudel
+ *   Copyright (C) 2009, 2010 Pierre Wieser
+ *   Nautilus-Actions is free software, licensed under GPLv2 or later.
+ * </programlisting>
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_core_utils_print_version( void )
diff --git a/src/core/na-gconf-monitor.c b/src/core/na-gconf-monitor.c
index 43678b3..2f615f7 100644
--- a/src/core/na-gconf-monitor.c
+++ b/src/core/na-gconf-monitor.c
@@ -36,13 +36,13 @@
 
 /* private class data
  */
-struct NAGConfMonitorClassPrivate {
+struct _NAGConfMonitorClassPrivate {
 	void *empty;						/* so that gcc -pedantic is happy */
 };
 
 /* private instance data
  */
-struct NAGConfMonitorPrivate {
+struct _NAGConfMonitorPrivate {
 	gboolean              dispose_has_run;
 	GConfClient          *gconf;
 	gchar                *path;
@@ -189,11 +189,13 @@ instance_finalize( GObject *object )
  *
  * Initializes the monitoring of a GConf path.
  *
+ * This monitoring will only be stopped when object is released, via
+ * g_object_unref().
+ *
  * Returns: a new #NAGConfMonitor object, which will monitor the given path,
  * triggeering the @handler in case of modifications.
  *
- * This monitoring will only be stopped when object is released, via
- * g_object_unref().
+ * Since: Nautilus-Actions v 2.30.
  */
 NAGConfMonitor *
 na_gconf_monitor_new( const gchar *path, GConfClientNotifyFunc handler, gpointer user_data )
@@ -259,6 +261,8 @@ install_monitor( NAGConfMonitor *monitor )
  * @monitors: a list of #NAGConfMonitors.
  *
  * Release allocated monitors.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_gconf_monitor_release_monitors( GList *monitors )
diff --git a/src/core/na-gconf-utils.c b/src/core/na-gconf-utils.c
index f30c290..b4632e9 100644
--- a/src/core/na-gconf-utils.c
+++ b/src/core/na-gconf-utils.c
@@ -43,12 +43,14 @@ static gboolean    sync_gconf( GConfClient *gconf, gchar **message );
 
 /**
  * na_gconf_utils_get_subdirs:
- * @gconf: a  #GConfClient instance.
+ * @gconf: a GConfClient instance.
  * @path: a full path to be readen.
  *
  * Returns: a list of full path subdirectories.
  *
- * The returned list should be #na_gconf_utils_free_subdirs() by the caller.
+ * The returned list should be na_gconf_utils_free_subdirs() by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 GSList *
 na_gconf_utils_get_subdirs( GConfClient *gconf, const gchar *path )
@@ -70,9 +72,11 @@ na_gconf_utils_get_subdirs( GConfClient *gconf, const gchar *path )
 
 /**
  * na_gconf_utils_free_subdirs:
- * @subdirs: the subdirectory list as returned from #na_gconf_utils_get_subdirs().
+ * @subdirs: the subdirectory list as returned from na_gconf_utils_get_subdirs().
  *
  * Release the list.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_gconf_utils_free_subdirs( GSList *subdirs )
@@ -82,11 +86,13 @@ na_gconf_utils_free_subdirs( GSList *subdirs )
 
 /**
  * na_gconf_utils_has_entry:
- * @entries: the list of entries as returned by #na_gconf_utils_get_entries().
+ * @entries: the list of entries as returned by na_gconf_utils_get_entries().
  * @entry: the entry to be tested.
  *
  * Returns: %TRUE if the given @entry exists in the specified @entries,
  * %FALSE else.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gboolean
 na_gconf_utils_has_entry( GSList *entries, const gchar *entry )
@@ -107,7 +113,7 @@ na_gconf_utils_has_entry( GSList *entries, const gchar *entry )
 
 /**
  * na_gconf_utils_get_entries:
- * @gconf: a  #GConfClient instance.
+ * @gconf: a  GConfClient instance.
  * @path: a full path to be readen.
  *
  * Loads all the key=value pairs of the specified key.
@@ -117,6 +123,8 @@ na_gconf_utils_has_entry( GSList *entries, const gchar *entry )
  * The returned list is not recursive : it contains only the immediate
  * children of @path. To free the returned list, call
  * na_gconf_utils_free_entries().
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 GSList *
 na_gconf_utils_get_entries( GConfClient *gconf, const gchar *path )
@@ -146,6 +154,8 @@ na_gconf_utils_get_entries( GConfClient *gconf, const gchar *path )
  *
  * If the entry was not found, or was not of boolean type, @value is set
  * to %FALSE.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gboolean
 na_gconf_utils_get_bool_from_entries( GSList *entries, const gchar *entry, gboolean *value )
@@ -193,6 +203,8 @@ na_gconf_utils_get_bool_from_entries( GSList *entries, const gchar *entry, gbool
  * to %NULL.
  *
  * If @value is returned not NULL, it should be g_free() by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gboolean
 na_gconf_utils_get_string_from_entries( GSList *entries, const gchar *entry, gchar **value )
@@ -239,8 +251,10 @@ na_gconf_utils_get_string_from_entries( GSList *entries, const gchar *entry, gch
  * If the entry was not found, or was not of string list type, @value
  * is set to %NULL.
  *
- * If @value is returned not NULL, it should be na_utils_free_string_list()
+ * If @value is returned not NULL, it should be na_core_utils_slist_free()
  * by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gboolean
 na_gconf_utils_get_string_list_from_entries( GSList *entries, const gchar *entry, GSList **value )
@@ -285,6 +299,8 @@ na_gconf_utils_get_string_list_from_entries( GSList *entries, const gchar *entry
  * @entries: a list of #GConfEntry as returned by na_gconf_utils_get_entries().
  *
  * Dumps the content of the entries.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_gconf_utils_dump_entries( GSList *entries )
@@ -343,6 +359,8 @@ dump_entry( GConfEntry *entry, void *user_data )
  * @entries: a list of #GConfEntry as returned by na_gconf_utils_get_entries().
  *
  * Releases the provided list.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_gconf_utils_free_entries( GSList *entries )
@@ -353,13 +371,15 @@ na_gconf_utils_free_entries( GSList *entries )
 
 /**
  * na_gconf_utils_read_bool:
- * @gconf: a #GConfClient instance.
+ * @gconf: a GConfClient instance.
  * @path: the full path to the key.
  * @use_schema: whether to use the default value from schema, or not.
  * @default_value: default value to be used if schema is not used or
  * doesn't exist.
  *
  * Returns: the required boolean value.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gboolean
 na_gconf_utils_read_bool( GConfClient *gconf, const gchar *path, gboolean use_schema, gboolean default_value )
@@ -382,13 +402,15 @@ na_gconf_utils_read_bool( GConfClient *gconf, const gchar *path, gboolean use_sc
 
 /**
  * na_gconf_utils_read_int:
- * @gconf: a #GConfClient instance.
+ * @gconf: a GConfClient instance.
  * @path: the full path to the key.
  * @use_schema: whether to use the default value from schema, or not.
  * @default_value: default value to be used if schema is not used or
  * doesn't exist.
  *
  * Returns: the required integer value.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gint
 na_gconf_utils_read_int( GConfClient *gconf, const gchar *path, gboolean use_schema, gint default_value )
@@ -412,7 +434,7 @@ na_gconf_utils_read_int( GConfClient *gconf, const gchar *path, gboolean use_sch
 
 /**
  * na_gconf_utils_read_string:
- * @gconf: a #GConfClient instance.
+ * @gconf: a GConfClient instance.
  * @path: the full path to the key.
  * @use_schema: whether to use the default value from schema, or not.
  * @default_value: default value to be used if schema is not used or
@@ -420,6 +442,8 @@ na_gconf_utils_read_int( GConfClient *gconf, const gchar *path, gboolean use_sch
  *
  * Returns: the required string value in a newly allocated string which
  * should be g_free() by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gchar *
 na_gconf_utils_read_string( GConfClient *gconf, const gchar *path, gboolean use_schema, const gchar *default_value )
@@ -444,13 +468,15 @@ na_gconf_utils_read_string( GConfClient *gconf, const gchar *path, gboolean use_
 
 /**
  * na_gconf_utils_read_string_list:
- * @gconf: a #GConfClient instance.
+ * @gconf: a GConfClient instance.
  * @path: the full path to the key to be read.
  *
  * Returns: a list of strings,
  * or %NULL if the entry was not found or was not of string list type.
  *
- * The returned list must be released with na_utils_free_string_list().
+ * The returned list must be released with na_core_utils_slist_free().
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 GSList *
 na_gconf_utils_read_string_list( GConfClient *gconf, const gchar *path )
@@ -474,7 +500,7 @@ na_gconf_utils_read_string_list( GConfClient *gconf, const gchar *path )
 
 /**
  * na_gconf_utils_write_bool:
- * @gconf: a #GConfClient instance.
+ * @gconf: a GConfClient instance.
  * @path: the full path to the key.
  * @value: the value to be written.
  * @message: a pointer to a gchar * which will be allocated if needed.
@@ -485,6 +511,8 @@ na_gconf_utils_read_string_list( GConfClient *gconf, const gchar *path )
  *
  * If returned not NULL, the @message contains an error message.
  * It should be g_free() by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gboolean
 na_gconf_utils_write_bool( GConfClient *gconf, const gchar *path, gboolean value, gchar **message )
@@ -509,7 +537,7 @@ na_gconf_utils_write_bool( GConfClient *gconf, const gchar *path, gboolean value
 
 /**
  * na_gconf_utils_write_int:
- * @gconf: a #GConfClient instance.
+ * @gconf: a GConfClient instance.
  * @path: the full path to the key.
  * @value: the value to be written.
  * @message: a pointer to a gchar * which will be allocated if needed.
@@ -520,6 +548,8 @@ na_gconf_utils_write_bool( GConfClient *gconf, const gchar *path, gboolean value
  *
  * If returned not NULL, the @message contains an error message.
  * It should be g_free() by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gboolean
 na_gconf_utils_write_int( GConfClient *gconf, const gchar *path, gint value, gchar **message )
@@ -544,7 +574,7 @@ na_gconf_utils_write_int( GConfClient *gconf, const gchar *path, gint value, gch
 
 /**
  * na_gconf_utils_write_string:
- * @gconf: a #GConfClient instance.
+ * @gconf: a GConfClient instance.
  * @path: the full path to the key.
  * @value: the value to be written.
  * @message: a pointer to a gchar * which will be allocated if needed.
@@ -555,6 +585,8 @@ na_gconf_utils_write_int( GConfClient *gconf, const gchar *path, gint value, gch
  *
  * If returned not NULL, the @message contains an error message.
  * It should be g_free() by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gboolean
 na_gconf_utils_write_string( GConfClient *gconf, const gchar *path, const gchar *value, gchar **message )
@@ -579,7 +611,7 @@ na_gconf_utils_write_string( GConfClient *gconf, const gchar *path, const gchar
 
 /**
  * na_gconf_utils_write_string_list:
- * @gconf: a #GConfClient instance.
+ * @gconf: a GConfClient instance.
  * @path: the full path to the key.
  * @value: the list of values to be written.
  * @message: a pointer to a gchar * which will be allocated if needed.
@@ -590,6 +622,8 @@ na_gconf_utils_write_string( GConfClient *gconf, const gchar *path, const gchar
  *
  * If returned not NULL, the @message contains an error message.
  * It should be g_free() by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gboolean
 na_gconf_utils_write_string_list( GConfClient *gconf, const gchar *path, GSList *value, gchar **message )
@@ -619,13 +653,15 @@ na_gconf_utils_write_string_list( GConfClient *gconf, const gchar *path, GSList
 
 /**
  * na_gconf_utils_remove_entry:
- * @gconf: a #GConfClient instance.
+ * @gconf: a GConfClient instance.
  * @path: the full path to the entry.
  * @message: a pointer to a gchar * which will be allocated if needed.
  *
  * Removes an entry from user preferences.
  *
  * Returns: %TRUE if the operation was successfull, %FALSE else.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gboolean
 na_gconf_utils_remove_entry( GConfClient *gconf, const gchar *path, gchar **message )
@@ -662,6 +698,8 @@ na_gconf_utils_remove_entry( GConfClient *gconf, const gchar *path, gchar **mess
  * Returns: a newly allocated list of strings, which should be
  * na_core_utils_slist_free() by the caller, or %NULL if the provided
  * string was not of the GConf form.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 GSList *
 na_gconf_utils_slist_from_string( const gchar *value )
@@ -695,6 +733,8 @@ na_gconf_utils_slist_from_string( const gchar *value )
  *
  * Returns: the content of @slist, with the GConf format, as a newly
  * allocated string which should be g_free() by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gchar *
 na_gconf_utils_slist_to_string( GSList *slist )
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]