GNOME.org
 

[nautilus-actions] Reference manual: document NAIFactoryObject interface

commit c67efaeda89493934d357016a010b7890c9183cc
Author: Pierre Wieser <pwieser trychlos org>
Date:   Fri Dec 10 00:30:45 2010 +0100

    Reference manual: document NAIFactoryObject interface

 ChangeLog                                    |    7 ++
 docs/reference/nautilus-actions-sections.txt |   10 ++-
 src/api/na-ifactory-object.h                 |   70 +++++++++------
 src/core/na-ifactory-object.c                |  124 ++++++++++++++++++-------
 src/core/na-ifactory-provider.c              |    2 +-
 5 files changed, 145 insertions(+), 68 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index c42daea..91e4d85 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,12 @@
 2010-12-09 Pierre Wieser <pwieser trychlos org>
 
+	Document NAIFactoryObject interface.
+
+	* docs/reference/nautilus-actions-sections.txt:
+	* src/api/na-ifactory-object.h:
+	* src/core/na-ifactory-object.c:
+	* src/core/na-ifactory-provider.c: Updated accordingly.
+
 	Document NAIFactoryProvider interface.
 
 	* docs/reference/nautilus-actions-docs.xml:
diff --git a/docs/reference/nautilus-actions-sections.txt b/docs/reference/nautilus-actions-sections.txt
index 849bf70..8e5092f 100644
--- a/docs/reference/nautilus-actions-sections.txt
+++ b/docs/reference/nautilus-actions-sections.txt
@@ -90,19 +90,21 @@ NAIFactoryProviderInterfacePrivate
 <SECTION>
 <FILE>ifactory-object</FILE>
 NA_IFACTORY_OBJECT_TYPE
+NA_IFACTORY_OBJECT
+NA_IS_IFACTORY_OBJECT
 NA_IFACTORY_OBJECT_GET_INTERFACE
 NAIFactoryObject
-NAIFactoryObjectInterfacePrivate
 NAIFactoryObjectInterface
-na_ifactory_object_get_data_groups
 na_ifactory_object_get_data_boxed
+na_ifactory_object_get_data_groups
 na_ifactory_object_get_as_void
 na_ifactory_object_set_from_void
 
 <SUBSECTION Standard>
-NA_IFACTORY_OBJECT
-NA_IS_IFACTORY_OBJECT
 na_ifactory_object_get_type
+
+<SUBSECTION Private>
+NAIFactoryObjectInterfacePrivate
 </SECTION>
 
 <SECTION>
diff --git a/src/api/na-ifactory-object.h b/src/api/na-ifactory-object.h
index 4d72731..84f9ce6 100644
--- a/src/api/na-ifactory-object.h
+++ b/src/api/na-ifactory-object.h
@@ -31,25 +31,6 @@
 #ifndef __NAUTILUS_ACTIONS_API_NA_IFACTORY_OBJECT_H__
 #define __NAUTILUS_ACTIONS_API_NA_IFACTORY_OBJECT_H__
 
-/**
- * SECTION: ifactory-object
- * @section_id: ifactory-object
- * @title: NAIFactoryObject (na-ifactory-object.h title)
- * @short_description: #NAIFactoryObject interface definition (na-ifactory-object.h short description).
- * @include: nautilus-actions/na-ifactory_object.h
- *
- * This interface must be implemented by #NAObject-derived objects which
- * should take advantage of data factory management system.
- *
- * A #NAObject-derived which should implement this #NAIFactoryObject
- * interface must meet following conditions:
- * - must accept an empty constructor
- *
- * Elementary data are implemented as a #GList of #NADataBoxed objects.
- *
- * Since: Nautilus-Actions v 2.30 (API version 1)
- */
-
 #include "na-data-def.h"
 #include "na-data-boxed.h"
 #include "na-ifactory-provider-provider.h"
@@ -61,10 +42,25 @@ G_BEGIN_DECLS
 #define NA_IS_IFACTORY_OBJECT( instance )				( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_IFACTORY_OBJECT_TYPE ))
 #define NA_IFACTORY_OBJECT_GET_INTERFACE( instance )	( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_IFACTORY_OBJECT_TYPE, NAIFactoryObjectInterface ))
 
-typedef struct NAIFactoryObject                 NAIFactoryObject;
+typedef struct _NAIFactoryObject                 NAIFactoryObject;
 
-typedef struct NAIFactoryObjectInterfacePrivate NAIFactoryObjectInterfacePrivate;
+typedef struct _NAIFactoryObjectInterfacePrivate NAIFactoryObjectInterfacePrivate;
 
+/**
+ * NAIFactoryObjectInterface:
+ * @get_version: returns the version of this interface the NAObjectItem implements.
+ * @get_groups:  returns a pointer to the NADataGroup which defines this object.
+ * @copy:        post copy callback.
+ * @are_equal:   tests if two NAObjectItem are equals.
+ * @is_valid:    tests if one NAObjectItem is valid.
+ * @read_start:  triggered before serializing a NAObjectItem.
+ * @read_done:   triggered after a NAObjectItem has been serialized.
+ * @write_start: triggered before unserializing a NAObjectItem.
+ * @write_done:  triggered after a NAObjectItem has been unserialized.
+ *
+ * In order to take full advantage of our data managament system, NAOBjectItem-derived
+ * objects all implement this #NAIFactoryObject interface.
+ */
 typedef struct {
 	GTypeInterface                    parent;
 	NAIFactoryObjectInterfacePrivate *private;
@@ -73,9 +69,11 @@ typedef struct {
 	 * get_version:
 	 * @instance: this #NAIFactoryObject instance.
 	 *
+	 * Defaults to 1.
+	 *
 	 * Returns: the version of this interface supported by @instance implementation.
 	 *
-	 * Defaults to 1.
+	 * Since: Nautilus-Actions v 2.30, NAIFactoryObject interface v 1.
 	 */
 	guint         ( *get_version )( const NAIFactoryObject *instance );
 
@@ -84,6 +82,8 @@ typedef struct {
 	 * @instance: this #NAIFactoryObject instance.
 	 *
 	 * Returns: a pointer to the NADataGroup which defines this object.
+	 *
+	 * Since: Nautilus-Actions v 2.30, NAIFactoryObject interface v 1.
 	 */
 	NADataGroup * ( *get_groups ) ( const NAIFactoryObject *instance );
 
@@ -95,6 +95,8 @@ typedef struct {
 	 * This function is triggered after having copied @source to
 	 * @instance target. This later may take advantage of this call
 	 * to do some particular copy tasks.
+	 *
+	 * Since: Nautilus-Actions v 2.30, NAIFactoryObject interface v 1.
 	 */
 	void          ( *copy )       ( NAIFactoryObject *instance, const NAIFactoryObject *source );
 
@@ -103,10 +105,12 @@ typedef struct {
 	 * @a: the first #NAIFactoryObject instance.
 	 * @b: the second #NAIFactoryObject instance.
 	 *
-	 * Returns: %TRUE if @a is equal to @b.
-	 *
 	 * This function is triggered after all elementary data comparisons
 	 * have been sucessfully made.
+	 *
+	 * Returns: %TRUE if @a is equal to @b.
+	 *
+	 * Since: Nautilus-Actions v 2.30, NAIFactoryObject interface v 1.
 	 */
 	gboolean      ( *are_equal )  ( const NAIFactoryObject *a, const NAIFactoryObject *b );
 
@@ -114,10 +118,12 @@ typedef struct {
 	 * is_valid:
 	 * @object: the #NAIFactoryObject instance whose validity is to be checked.
 	 *
-	 * Returns: %TRUE if @object is valid.
-	 *
 	 * This function is triggered after all elementary data comparisons
 	 * have been sucessfully made.
+	 *
+	 * Returns: %TRUE if @object is valid.
+	 *
+	 * Since: Nautilus-Actions v 2.30, NAIFactoryObject interface v 1.
 	 */
 	gboolean      ( *is_valid )   ( const NAIFactoryObject *object );
 
@@ -130,6 +136,8 @@ typedef struct {
 	 *  may append messages to this list, but shouldn't reinitialize it.
 	 *
 	 * Called just before the object is unserialized.
+	 *
+	 * Since: Nautilus-Actions v 2.30, NAIFactoryObject interface v 1.
 	 */
 	void          ( *read_start ) ( NAIFactoryObject *instance, const NAIFactoryProvider *reader, void *reader_data, GSList **messages );
 
@@ -142,6 +150,8 @@ typedef struct {
 	 *  may append messages to this list, but shouldn't reinitialize it.
 	 *
 	 * Called when the object has been unserialized.
+	 *
+	 * Since: Nautilus-Actions v 2.30, NAIFactoryObject interface v 1.
 	 */
 	void          ( *read_done )  ( NAIFactoryObject *instance, const NAIFactoryProvider *reader, void *reader_data, GSList **messages );
 
@@ -156,6 +166,8 @@ typedef struct {
 	 * Called just before the object is serialized.
 	 *
 	 * Returns: a NAIIOProvider operation return code.
+	 *
+	 * Since: Nautilus-Actions v 2.30, NAIFactoryObject interface v 1.
 	 */
 	guint         ( *write_start )( NAIFactoryObject *instance, const NAIFactoryProvider *writer, void *writer_data, GSList **messages );
 
@@ -170,6 +182,8 @@ typedef struct {
 	 * Called when the object has been serialized.
 	 *
 	 * Returns: a NAIIOProvider operation return code.
+	 *
+	 * Since: Nautilus-Actions v 2.30, NAIFactoryObject interface v 1.
 	 */
 	guint         ( *write_done ) ( NAIFactoryObject *instance, const NAIFactoryProvider *writer, void *writer_data, GSList **messages );
 }
@@ -177,10 +191,10 @@ typedef struct {
 
 GType        na_ifactory_object_get_type( void );
 
-NADataGroup *na_ifactory_object_get_data_groups( const NAIFactoryObject *object );
-
 NADataBoxed *na_ifactory_object_get_data_boxed ( const NAIFactoryObject *object, const gchar *name );
 
+NADataGroup *na_ifactory_object_get_data_groups( const NAIFactoryObject *object );
+
 void        *na_ifactory_object_get_as_void    ( const NAIFactoryObject *object, const gchar *name );
 
 void         na_ifactory_object_set_from_void  ( NAIFactoryObject *object, const gchar *name, const void *data );
diff --git a/src/core/na-ifactory-object.c b/src/core/na-ifactory-object.c
index 45104a6..9b6798a 100644
--- a/src/core/na-ifactory-object.c
+++ b/src/core/na-ifactory-object.c
@@ -38,9 +38,55 @@
 
 #include "na-factory-object.h"
 
+/**
+ * SECTION: ifactory-object
+ * @title: NAIFactoryObject
+ * @short_description: The interface implemented by NAObjectItem-derived objects.
+ * @include: nautilus-actions/na-ifactory_object.h
+ *
+ * This interface is implemented by #NAObjectItem derived objects so that they
+ * can take advantage of our data factory management system.
+ *
+ * A #NAObjectItem derived object which would implement this #NAIFactoryObject
+ * interface must meet following conditions:
+ * <itemizedlist>
+ *   <listitem>
+ *     <para>
+ *       accept an empty constructor
+ *     </para>
+ *   </listitem>
+ * </itemizedlist>
+ *
+ * <refsect2>
+ *  <title>Versions historic</title>
+ *  <table>
+ *    <title>Historic of the versions of the #NAIFactoryObject 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>#NAIFactoryObject 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 interface data
  */
-struct NAIFactoryObjectInterfacePrivate {
+struct _NAIFactoryObjectInterfacePrivate {
 	void *empty;					/* so that gcc -pedantic is happy */
 };
 
@@ -142,43 +188,17 @@ ifactory_object_get_version( const NAIFactoryObject *instance )
 }
 
 /**
- * na_ifactory_object_get_data_groups:
- * @object: a #NAIFactoryObject object.
- *
- * Returns: The #NADataGroup groups definition, or %NULL.
- *
- * The returned #NADataGroup is owned by the #NAIFactoryObject @object,
- * and should not be released by the caller.
- */
-NADataGroup *
-na_ifactory_object_get_data_groups( const NAIFactoryObject *object )
-{
-	NADataGroup *groups;
-
-	g_return_val_if_fail( NA_IS_IFACTORY_OBJECT( object ), NULL );
-
-	groups = NULL;
-
-	if( ifactory_object_initialized && !ifactory_object_finalized ){
-
-		if( NA_IFACTORY_OBJECT_GET_INTERFACE( object )->get_groups ){
-			groups = NA_IFACTORY_OBJECT_GET_INTERFACE( object )->get_groups( object );
-		}
-	}
-
-	return( groups );
-}
-
-/**
  * na_ifactory_object_get_data_boxed:
  * @object: a #NAIFactoryObject object.
  * @name: the name of the elementary data we are searching for.
  *
+ * The returned #NADataBoxed is owned by #NAIFactoryObject @object, and
+ * should not be released by the caller.
+ *
  * Returns: The #NADataBoxed object which contains the specified data,
  * or %NULL.
  *
- * The returned #NADataBoxed is owned by #NAIFactoryObject @object, and
- * should not be released by the caller.
+ * Since: Nautilus-Actions v 2.30, NAIFactoryObject interface v 1.
  */
 NADataBoxed *
 na_ifactory_object_get_data_boxed( const NAIFactoryObject *object, const gchar *name )
@@ -206,16 +226,48 @@ na_ifactory_object_get_data_boxed( const NAIFactoryObject *object, const gchar *
 }
 
 /**
+ * na_ifactory_object_get_data_groups:
+ * @object: a #NAIFactoryObject object.
+ *
+ * The returned #NADataGroup is owned by the #NAIFactoryObject @object,
+ * and should not be released by the caller.
+ *
+ * Returns: The #NADataGroup groups definition, or %NULL.
+ *
+ * Since: Nautilus-Actions v 2.30, NAIFactoryObject interface v 1.
+ */
+NADataGroup *
+na_ifactory_object_get_data_groups( const NAIFactoryObject *object )
+{
+	NADataGroup *groups;
+
+	g_return_val_if_fail( NA_IS_IFACTORY_OBJECT( object ), NULL );
+
+	groups = NULL;
+
+	if( ifactory_object_initialized && !ifactory_object_finalized ){
+
+		if( NA_IFACTORY_OBJECT_GET_INTERFACE( object )->get_groups ){
+			groups = NA_IFACTORY_OBJECT_GET_INTERFACE( object )->get_groups( object );
+		}
+	}
+
+	return( groups );
+}
+
+/**
  * na_ifactory_object_get_as_void:
  * @object: this #NAIFactoryObject instance.
  * @name: the elementary data whose value is to be got.
  *
- * Returns: the searched value.
- *
- * If the type of the value is NAFD_TYPE_STRING, NAFD_TYPE_LOCALE_STRING,
- * or NAFD_TYPE_STRING_LIST, then the returned value is a newly allocated
+ * If the type of the value is %NAFD_TYPE_STRING, %NAFD_TYPE_LOCALE_STRING,
+ * or %NAFD_TYPE_STRING_LIST, then the returned value is a newly allocated
  * one and should be g_free() (resp. na_core_utils_slist_free()) by the
  * caller.
+ *
+ * Returns: the searched value.
+ *
+ * Since: Nautilus-Actions v 2.30, NAIFactoryObject interface v 1.
  */
 void *
 na_ifactory_object_get_as_void( const NAIFactoryObject *object, const gchar *name )
@@ -232,6 +284,8 @@ na_ifactory_object_get_as_void( const NAIFactoryObject *object, const gchar *nam
  * @data: the value to set.
  *
  * Set the elementary data with the given value.
+ *
+ * Since: Nautilus-Actions v 2.30, NAIFactoryObject interface v 1.
  */
 void
 na_ifactory_object_set_from_void( NAIFactoryObject *object, const gchar *name, const void *data )
diff --git a/src/core/na-ifactory-provider.c b/src/core/na-ifactory-provider.c
index b8f925c..fa8ced1 100644
--- a/src/core/na-ifactory-provider.c
+++ b/src/core/na-ifactory-provider.c
@@ -308,7 +308,7 @@ na_ifactory_provider_read_item( const NAIFactoryProvider *reader, void *reader_d
  * na_ifactory_provider_write_item:
  * @writer: the instance which implements this #NAIFactoryProvider interface.
  * @writer_data: instance data.
- * @object: the #NAIFactoryObject-derived object to be serialized.
+ * @object: the #NAIFactoryObject derived object to be serialized.
  * @messages: a pointer to a #GSList list of strings; the implementation
  *  may append messages to this list, but shouldn't reinitialize it.
  *
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]