GNOME.org
 

[nautilus-actions] Reference manual: document NADataBoxed class

commit 4335ea9ad35f9dcccac378c49c9a8c5e8f32d0f8
Author: Pierre Wieser <pwieser trychlos org>
Date:   Fri Dec 10 01:53:56 2010 +0100

    Reference manual: document NADataBoxed class

 ChangeLog                                    |    9 +++
 docs/reference/nautilus-actions-docs.xml     |    4 +-
 docs/reference/nautilus-actions-sections.txt |   78 +++++++++++++------------
 src/api/na-data-boxed.h                      |   22 ++-----
 src/api/na-data-types.h                      |   41 ++++++--------
 src/core/na-data-boxed.c                     |   66 ++++++++++++++++++++++
 src/core/na-data-types.c                     |   13 ++++-
 7 files changed, 153 insertions(+), 80 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index cfe05b6..8aecd60 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,14 @@
 2010-12-09 Pierre Wieser <pwieser trychlos org>
 
+	Document NADataBoxed class.
+
+	* docs/reference/nautilus-actions-docs.xml:
+	* docs/reference/nautilus-actions-sections.txt:
+	* src/api/na-data-boxed.h:
+	* src/api/na-data-types.h:
+	* src/core/na-data-boxed.c:
+	* src/core/na-data-types.c: Updated accordingly.
+
 	Document NADataDef and NADataGroup structures.
 
 	* docs/reference/nautilus-actions-docs.xml:
diff --git a/docs/reference/nautilus-actions-docs.xml b/docs/reference/nautilus-actions-docs.xml
index 79f7b01..667698a 100644
--- a/docs/reference/nautilus-actions-docs.xml
+++ b/docs/reference/nautilus-actions-docs.xml
@@ -61,9 +61,10 @@
     <title>Data Factory Management System</title>
     <xi:include href="xml/ifactory-provider.xml" />
     <xi:include href="xml/ifactory-object.xml" />
+    <xi:include href="xml/data-type.xml"/>
     <xi:include href="xml/data-def.xml"/>
     <xi:include href="xml/ifactory-data.xml"/>
-    <xi:include href="xml/na-data-boxed.xml"/>
+    <xi:include href="xml/data-boxed.xml"/>
   </chapter>
 
   <chapter>
@@ -77,7 +78,6 @@
     <xi:include href="xml/na-object.xml"/>
     <xi:include href="xml/na-object-profile.xml"/>
     <xi:include href="xml/na-iduplicable.xml"/>
-    <xi:include href="xml/na-data-types.xml"/>
     <xi:include href="xml/na-gconf-utils.xml"/>
     <xi:include href="xml/na-core-utils.xml"/>
     <xi:include href="xml/na-object-api.xml"/>
diff --git a/docs/reference/nautilus-actions-sections.txt b/docs/reference/nautilus-actions-sections.txt
index df067a2..09e2935 100644
--- a/docs/reference/nautilus-actions-sections.txt
+++ b/docs/reference/nautilus-actions-sections.txt
@@ -17,6 +17,7 @@ NAIIOProvider
 NAIIOProviderInterface
 NAIIOProviderWritabilityStatus
 NAIIOProviderOperationStatus
+IIO_PROVIDER_SIGNAL_ITEM_CHANGED
 na_iio_provider_item_changed
 
 <SUBSECTION Standard>
@@ -58,6 +59,7 @@ NA_IS_IEXPORTER
 NA_IEXPORTER_GET_INTERFACE
 NAIExporter
 NAIExporterInterface
+NAIExporterExportStatus
 NAIExporterFormat
 NAIExporterFileParms
 NAIExporterBufferParms
@@ -108,6 +110,12 @@ NAIFactoryObjectInterfacePrivate
 </SECTION>
 
 <SECTION>
+<FILE>data-type</FILE>
+NAFactoryDataType
+na_data_types_get_gconf_dump_key
+</SECTION>
+
+<SECTION>
 <FILE>data-def</FILE>
 NADataDef
 NADataGroup
@@ -176,6 +184,37 @@ NAFO_DATA_CAPABILITITES
 </SECTION>
 
 <SECTION>
+<FILE>data-boxed</FILE>
+NA_DATA_BOXED_TYPE
+NA_DATA_BOXED
+NA_IS_DATA_BOXED
+NADataBoxed
+na_data_boxed_new
+na_data_boxed_get_data_def
+na_data_boxed_get_param_spec
+na_data_boxed_are_equal
+na_data_boxed_is_default
+na_data_boxed_is_valid
+na_data_boxed_dump
+na_data_boxed_set_data_def
+na_data_boxed_get_as_string
+na_data_boxed_get_as_void
+na_data_boxed_get_as_value
+na_data_boxed_set_from_boxed
+na_data_boxed_set_from_string
+na_data_boxed_set_from_value
+na_data_boxed_set_from_void
+
+<SUBSECTION Standard>
+na_data_boxed_get_type
+NA_DATA_BOXED_CLASS
+NA_IS_DATA_BOXED_CLASS
+NA_DATA_BOXED_GET_CLASS
+NADataBoxedPrivate
+NADataBoxedClassPrivate
+</SECTION>
+
+<SECTION>
 <FILE>dbus</FILE>
 <TITLE>DBus (nautilus-actions-sections title)</TITLE>
 NAUTILUS_ACTIONS_DBUS_SERVICE
@@ -275,6 +314,7 @@ na_object_item_count_items
 na_object_item_unref_items
 na_object_item_unref_items_rec
 na_object_item_rebuild_children_slist
+na_object_item_deals_with_version
 
 <SUBSECTION Standard>
 NA_OBJECT_ITEM
@@ -317,6 +357,7 @@ NAObjectProfileClassPrivate
 NAObjectProfile
 na_object_profile_new
 na_object_profile_new_with_defaults
+na_object_profile_convert_v2_to_last
 
 <SUBSECTION Standard>
 NA_OBJECT_PROFILE
@@ -388,43 +429,6 @@ NA_GCONF_MONITOR_GET_CLASS
 </SECTION>
 
 <SECTION>
-<FILE>data-boxed</FILE>
-<TITLE>NADataBoxed</TITLE>
-NA_DATA_BOXED_TYPE
-NADataBoxedPrivate
-NADataBoxedClassPrivate
-NADataBoxed
-na_data_boxed_get_param_spec
-na_data_boxed_new
-na_data_boxed_get_data_def
-na_data_boxed_are_equal
-na_data_boxed_is_default
-na_data_boxed_is_valid
-na_data_boxed_dump
-na_data_boxed_set_data_def
-na_data_boxed_get_as_string
-na_data_boxed_get_as_void
-na_data_boxed_get_as_value
-na_data_boxed_set_from_boxed
-na_data_boxed_set_from_string
-na_data_boxed_set_from_value
-na_data_boxed_set_from_void
-
-<SUBSECTION Standard>
-NA_DATA_BOXED
-NA_IS_DATA_BOXED
-na_data_boxed_get_type
-NA_DATA_BOXED_CLASS
-NA_IS_DATA_BOXED_CLASS
-NA_DATA_BOXED_GET_CLASS
-</SECTION>
-
-<SECTION>
-<FILE>na-data-types</FILE>
-na_data_types_get_gconf_dump_key
-</SECTION>
-
-<SECTION>
 <FILE>na-gconf-utils</FILE>
 na_gconf_utils_get_subdirs
 na_gconf_utils_free_subdirs
diff --git a/src/api/na-data-boxed.h b/src/api/na-data-boxed.h
index 7b1a4ff..2125f6f 100644
--- a/src/api/na-data-boxed.h
+++ b/src/api/na-data-boxed.h
@@ -31,31 +31,23 @@
 #ifndef __NAUTILUS_ACTIONS_API_NA_DATA_BOXED_H__
 #define __NAUTILUS_ACTIONS_API_NA_DATA_BOXED_H__
 
-/**
- * SECTION: data-boxed
- * @short_description: #NADataBoxed class definition.
- * @include: nautilus-actions/na-data-boxed.h
- *
- * The object which encapsulates an elementary data of #NAIFactoryObject.
- * A #NADataBoxed object has a type and a value.
- */
-
 #include <glib-object.h>
 
 #include "na-data-def.h"
 
 G_BEGIN_DECLS
 
-#define NA_DATA_BOXED_TYPE					( na_data_boxed_get_type())
-#define NA_DATA_BOXED( object )				( G_TYPE_CHECK_INSTANCE_CAST( object, NA_DATA_BOXED_TYPE, NADataBoxed ))
-#define NA_DATA_BOXED_CLASS( klass )		( G_TYPE_CHECK_CLASS_CAST( klass, NA_DATA_BOXED_TYPE, NADataBoxedClass ))
-#define NA_IS_DATA_BOXED( object )			( G_TYPE_CHECK_INSTANCE_TYPE( object, NA_DATA_BOXED_TYPE ))
-#define NA_IS_DATA_BOXED_CLASS( klass )		( G_TYPE_CHECK_CLASS_TYPE(( klass ), NA_DATA_BOXED_TYPE ))
-#define NA_DATA_BOXED_GET_CLASS( object )	( G_TYPE_INSTANCE_GET_CLASS(( object ), NA_DATA_BOXED_TYPE, NADataBoxedClass ))
+#define NA_DATA_BOXED_TYPE                  ( na_data_boxed_get_type())
+#define NA_DATA_BOXED( object )             ( G_TYPE_CHECK_INSTANCE_CAST( object, NA_DATA_BOXED_TYPE, NADataBoxed ))
+#define NA_DATA_BOXED_CLASS( klass )        ( G_TYPE_CHECK_CLASS_CAST( klass, NA_DATA_BOXED_TYPE, NADataBoxedClass ))
+#define NA_IS_DATA_BOXED( object )          ( G_TYPE_CHECK_INSTANCE_TYPE( object, NA_DATA_BOXED_TYPE ))
+#define NA_IS_DATA_BOXED_CLASS( klass )     ( G_TYPE_CHECK_CLASS_TYPE(( klass ), NA_DATA_BOXED_TYPE ))
+#define NA_DATA_BOXED_GET_CLASS( object )   ( G_TYPE_INSTANCE_GET_CLASS(( object ), NA_DATA_BOXED_TYPE, NADataBoxedClass ))
 
 typedef struct NADataBoxedPrivate      NADataBoxedPrivate;
 
 typedef struct {
+	/*< private >*/
 	GObject             parent;
 	NADataBoxedPrivate *private;
 }
diff --git a/src/api/na-data-types.h b/src/api/na-data-types.h
index e6b1890..ea978a6 100644
--- a/src/api/na-data-types.h
+++ b/src/api/na-data-types.h
@@ -31,12 +31,6 @@
 #ifndef __NAUTILUS_ACTIONS_API_NA_FACTORY_DATA_TYPES_H__
 #define __NAUTILUS_ACTIONS_API_NA_FACTORY_DATA_TYPES_H__
 
-/**
- * SECTION: na_data
- * @short_description: NADataBoxed type definitions.
- * @include: nautilus-actions/na-data-types.h
- */
-
 #include <glib.h>
 
 G_BEGIN_DECLS
@@ -56,29 +50,28 @@ G_BEGIN_DECLS
  * IFactoryProvider implementations should provide a primitive for reading
  * (resp. writing) a value for each of these elementary data types.
  *
- * IMPORTANT NOTE
+ * <note>
+ *   <para>
  * Please note that this enumeration may be compiled in by the extensions.
  * They must so remain fixed, unless you want see strange effects (e.g.
- * an extension has been compiled with NAFD_TYPE_STRING = 2, while you
+ * an extension has been compiled with %NAFD_TYPE_STRING = 2, while you
  * have inserted another element, making it to 3 !) - or you know what
  * you are doing...
+ *   </para>
+ *   <para>
+ *     So, only add new items at the end of the enum. You have been warned!
+ *   </para>
+ * </note>
  */
-
-enum {
-	NAFD_TYPE_STRING = 1,				/* an ASCII string */
-
-	NAFD_TYPE_LOCALE_STRING,			/* a localized UTF-8 string */
-
-	NAFD_TYPE_BOOLEAN,					/* a boolean
-										 * can be initialized with "true" or "false" (case insensitive) */
-
-	NAFD_TYPE_STRING_LIST,				/* a list of ASCII strings */
-
-	NAFD_TYPE_POINTER,					/* a ( void * ) pointer
-										 * should be initialized to NULL */
-
-	NAFD_TYPE_UINT,						/* an unsigned integer */
-};
+typedef enum {
+	NAFD_TYPE_STRING = 1,
+	NAFD_TYPE_LOCALE_STRING,
+	NAFD_TYPE_BOOLEAN,
+	NAFD_TYPE_STRING_LIST,
+	NAFD_TYPE_POINTER,
+	NAFD_TYPE_UINT
+}
+	NAFactoryDataType;
 
 const gchar *na_data_types_get_gconf_dump_key( guint type );
 
diff --git a/src/core/na-data-boxed.c b/src/core/na-data-boxed.c
index ee70308..0831c4f 100644
--- a/src/core/na-data-boxed.c
+++ b/src/core/na-data-boxed.c
@@ -41,6 +41,42 @@
 #include <api/na-data-types.h>
 #include <api/na-data-boxed.h>
 
+/**
+ * SECTION: data-boxed
+ * @title: NADataBoxed
+ * @short_description: The elementary data class definition.
+ * @include: nautilus-actions/na-data-boxed.h
+ *
+ * The object which encapsulates an elementary data of #NAIFactoryObject.
+ * A #NADataBoxed object has a type and a value.
+ *
+ * <refsect2>
+ *  <title>Versions historic</title>
+ *  <table>
+ *    <title>Historic of the versions of the #NADataBoxed interface</title>
+ *    <tgroup rowsep="1" colsep="1" align="center" cols="3">
+ *      <colspec colname="na-version" />
+ *      <colspec colname="api-version" />
+ *      <colspec colname="current" />
+ *      <thead>
+ *        <row>
+ *          <entry>&prodname; version</entry>
+ *          <entry>#NADataBoxed interface version</entry>
+ *          <entry></entry>
+ *        </row>
+ *      </thead>
+ *      <tbody>
+ *        <row>
+ *          <entry>since 2.30</entry>
+ *          <entry>1</entry>
+ *          <entry>current version</entry>
+ *        </row>
+ *      </tbody>
+ *    </tgroup>
+ *  </table>
+ * </refsect2>
+ */
+
 /* private class data
  */
 struct NADataBoxedClassPrivate {
@@ -404,6 +440,8 @@ get_data_boxed_fn( guint type )
  * @def: a #NADataDef definition structure.
  *
  * Returns: a #GParamSpec structure.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 GParamSpec *
 na_data_boxed_get_param_spec( const NADataDef *def )
@@ -430,6 +468,8 @@ na_data_boxed_get_param_spec( const NADataDef *def )
  * @def: the #NADataDef definition structure for this boxed.
  *
  * Returns: a newly allocated #NADataBoxed.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 NADataBoxed *
 na_data_boxed_new( const NADataDef *def )
@@ -451,6 +491,8 @@ na_data_boxed_new( const NADataDef *def )
  *
  * Returns: a pointer to the #NADataDef structure attached to the object.
  * Should never be %NULL.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 NADataDef *
 na_data_boxed_get_data_def( const NADataBoxed *boxed )
@@ -475,6 +517,8 @@ na_data_boxed_get_data_def( const NADataBoxed *boxed )
  * @b: the second #NADataBoxed object.
  *
  * Returns: %TRUE if the two boxeds are equal, %FALSE else.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gboolean
 na_data_boxed_are_equal( const NADataBoxed *a, const NADataBoxed *b )
@@ -511,6 +555,8 @@ na_data_boxed_are_equal( const NADataBoxed *a, const NADataBoxed *b )
  *
  * Returns: %TRUE if the #NADataBoxed holds its default value,
  * %FALSE else.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gboolean
 na_data_boxed_is_default( const NADataBoxed *boxed )
@@ -541,6 +587,8 @@ na_data_boxed_is_default( const NADataBoxed *boxed )
  * @boxed: the #NADataBoxed object whose validity is to be checked.
  *
  * Returns: %TRUE if the boxed is valid, %FALSE else.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gboolean
 na_data_boxed_is_valid( const NADataBoxed *boxed )
@@ -571,6 +619,8 @@ na_data_boxed_is_valid( const NADataBoxed *boxed )
  * @boxed: this #NADataBoxed object.
  *
  * Dump the content of @boxed.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_data_boxed_dump( const NADataBoxed *boxed )
@@ -594,6 +644,8 @@ na_data_boxed_dump( const NADataBoxed *boxed )
  * Changes the #NADataDef a @boxed points to:
  * -> the new type must be the same that the previous one.
  * -> value is unchanged.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_data_boxed_set_data_def( NADataBoxed *boxed, const NADataDef *new_def )
@@ -614,6 +666,8 @@ na_data_boxed_set_data_def( NADataBoxed *boxed, const NADataDef *new_def )
  *
  * Returns: the value of the @boxed, as a newly allocated string which
  * should be g_free() by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 gchar *
 na_data_boxed_get_as_string( const NADataBoxed *boxed )
@@ -648,6 +702,8 @@ na_data_boxed_get_as_string( const NADataBoxed *boxed )
  * If of type NAFD_TYPE_STRING, NAFD_TYPE_LOCALE_STRING OR
  * NAFD_TYPE_STRING_LIST, then the content is returned in a newly
  * allocated value, which should be released by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void *
 na_data_boxed_get_as_void( const NADataBoxed *boxed )
@@ -679,6 +735,8 @@ na_data_boxed_get_as_void( const NADataBoxed *boxed )
  * @value: the string to be set.
  *
  * Setup @value with the content of the @boxed.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_data_boxed_get_as_value( const NADataBoxed *boxed, GValue *value )
@@ -705,6 +763,8 @@ na_data_boxed_get_as_value( const NADataBoxed *boxed, GValue *value )
  * @value: the source #NADataBoxed.
  *
  * Copy value from @value to @boxed.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_data_boxed_set_from_boxed( NADataBoxed *boxed, const NADataBoxed *value )
@@ -736,6 +796,8 @@ na_data_boxed_set_from_boxed( NADataBoxed *boxed, const NADataBoxed *value )
  * @value: the string to be set.
  *
  * Evaluates the @value and set it to the @boxed.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_data_boxed_set_from_string( NADataBoxed *boxed, const gchar *value )
@@ -765,6 +827,8 @@ na_data_boxed_set_from_string( NADataBoxed *boxed, const gchar *value )
  * @value: the value whose content is to be got.
  *
  * Evaluates the @value and set it to the @boxed.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_data_boxed_set_from_value( NADataBoxed *boxed, const GValue *value )
@@ -794,6 +858,8 @@ na_data_boxed_set_from_value( NADataBoxed *boxed, const GValue *value )
  * @value: the value whose content is to be got.
  *
  * Evaluates the @value and set it to the @boxed.
+ *
+ * Since: Nautilus-Actions v 2.30.
  */
 void
 na_data_boxed_set_from_void( NADataBoxed *boxed, const void *value )
diff --git a/src/core/na-data-types.c b/src/core/na-data-types.c
index d878855..d4f26db 100644
--- a/src/core/na-data-types.c
+++ b/src/core/na-data-types.c
@@ -34,6 +34,13 @@
 
 #include <api/na-data-types.h>
 
+/**
+ * SECTION: data-type
+ * @title: NADataType
+ * @short_description: #NADataBoxed type definitions.
+ * @include: nautilus-actions/na-data-types.h
+ */
+
 typedef struct {
 	guint  type;
 	gchar *gconf_dump_key;
@@ -56,8 +63,10 @@ static FactoryType st_factory_type[] = {
  *
  * Returns: the GConf key suitable for this type.
  *
- * The returned key is owned by FactoryData, and should not be released
- * by the caller.
+ * The returned key is owned by the factory data management system, and
+ * should not be released by the caller.
+ *
+ * Since: Nautilus-Actions v 2.30
  */
 const gchar *
 na_data_types_get_gconf_dump_key( guint type )
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]