GNOME.org
 

[nautilus-actions] Reference manual: fix NAIExporter documentation

commit 4709edae83e2435a92effb3d8a9889b1b781e87d
Author: Pierre Wieser <pwieser trychlos org>
Date:   Thu Dec 9 20:14:49 2010 +0100

    Reference manual: fix NAIExporter documentation

 ChangeLog                                    |   10 ++
 docs/reference/nautilus-actions-sections.txt |   44 ++++----
 src/api/na-iexporter.h                       |  140 ++++++++++++++++----------
 src/api/na-iimporter.h                       |   36 ++++----
 src/api/na-iio-provider.h                    |   44 ++++-----
 src/core/na-exporter.c                       |    8 +-
 src/core/na-exporter.h                       |    2 +-
 src/core/na-iexporter.c                      |   37 +++++++-
 8 files changed, 199 insertions(+), 122 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 97b5d57..26ba519 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,15 @@
 2010-12-09 Pierre Wieser <pwieser trychlos org>
 
+	Fix NAIExporter reference manual.
+
+	* docs/reference/nautilus-actions-sections.txt:
+	* src/api/na-iexporter.h:
+	* src/api/na-iimporter.h:
+	* src/api/na-iio-provider.h:
+	* src/core/na-exporter.c:
+	* src/core/na-exporter.h:
+	* src/core/na-iexporter.c: Updated accordingly.
+
 	Fix NAIImporter reference manual.
 
 	* docs/reference/.gitignore:
diff --git a/docs/reference/nautilus-actions-sections.txt b/docs/reference/nautilus-actions-sections.txt
index ba6c875..43588d5 100644
--- a/docs/reference/nautilus-actions-sections.txt
+++ b/docs/reference/nautilus-actions-sections.txt
@@ -34,12 +34,12 @@ NA_IS_IIMPORTER
 NA_IIMPORTER_GET_INTERFACE
 NAIImporter
 NAIImporterInterface
-NAIImporterImportFromUriParms
-NAIImporterManageImportModeParms
-NAIImporterCheckFn
-NAIImporterAskUserFn
 NAIImporterImportMode
 NAIImporterImportStatus
+NAIImporterCheckFn
+NAIImporterAskUserFn
+NAIImporterImportFromUriParms
+NAIImporterManageImportModeParms
 na_iimporter_import_from_uri
 na_iimporter_manage_import_mode
 
@@ -51,6 +51,25 @@ NAIImporterInterfacePrivate
 </SECTION>
 
 <SECTION>
+<FILE>iexporter</FILE>
+NA_IEXPORTER_TYPE
+NA_IEXPORTER
+NA_IS_IEXPORTER
+NA_IEXPORTER_GET_INTERFACE
+NAIExporter
+NAIExporterInterface
+NAIExporterFormat
+NAIExporterFileParms
+NAIExporterBufferParms
+
+<SUBSECTION Standard>
+na_iexporter_get_type
+
+<SUBSECTION Private>
+NAIExporterInterfacePrivate
+</SECTION>
+
+<SECTION>
 <FILE>ifactory-object</FILE>
 NA_IFACTORY_OBJECT_TYPE
 NA_IFACTORY_OBJECT_GET_INTERFACE
@@ -84,23 +103,6 @@ na_ifactory_provider_get_type
 </SECTION>
 
 <SECTION>
-<FILE>iexporter</FILE>
-NA_IEXPORTER_TYPE
-NA_IEXPORTER_GET_INTERFACE
-NAIExporter
-NAIExporterFileParms
-NAIExporterBufferParms
-NAIExporterInterfacePrivate
-NAIExporterFormat
-NAIExporterInterface
-
-<SUBSECTION Standard>
-NA_IEXPORTER
-NA_IS_IEXPORTER
-na_iexporter_get_type
-</SECTION>
-
-<SECTION>
 <FILE>dbus</FILE>
 <TITLE>DBus (nautilus-actions-sections title)</TITLE>
 NAUTILUS_ACTIONS_DBUS_SERVICE
diff --git a/src/api/na-iexporter.h b/src/api/na-iexporter.h
index 4dd7747..69d58ad 100644
--- a/src/api/na-iexporter.h
+++ b/src/api/na-iexporter.h
@@ -31,50 +31,57 @@
 #ifndef __NAUTILUS_ACTIONS_API_NA_IEXPORTER_H__
 #define __NAUTILUS_ACTIONS_API_NA_IEXPORTER_H__
 
-/**
- * SECTION: iexporter
- * @section_id: iexporter
- * @title: NAIExporter (na-iexporter.h title)
- * @short_description: #NAIExporter interface definition na-iexporter.h short description)
- * @include: nautilus-actions/na-iexporter.h
- *
- * The #NAIExporter interface exports items to the outside world.
- *
- * Since: Nautilus-Actions v 2.30 (API version 1)
- */
-
 #include "na-object-item.h"
 
 G_BEGIN_DECLS
 
-#define NA_IEXPORTER_TYPE						( na_iexporter_get_type())
-#define NA_IEXPORTER( instance )				( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_IEXPORTER_TYPE, NAIExporter ))
-#define NA_IS_IEXPORTER( instance )				( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_IEXPORTER_TYPE ))
-#define NA_IEXPORTER_GET_INTERFACE( instance )	( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_IEXPORTER_TYPE, NAIExporterInterface ))
+#define NA_IEXPORTER_TYPE                       ( na_iexporter_get_type())
+#define NA_IEXPORTER( instance )                ( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_IEXPORTER_TYPE, NAIExporter ))
+#define NA_IS_IEXPORTER( instance )             ( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_IEXPORTER_TYPE ))
+#define NA_IEXPORTER_GET_INTERFACE( instance )  ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_IEXPORTER_TYPE, NAIExporterInterface ))
 
-typedef struct NAIExporter                 NAIExporter;
-typedef struct NAIExporterFileParms        NAIExporterFileParms;
-typedef struct NAIExporterBufferParms      NAIExporterBufferParms;
+typedef struct _NAIExporter                 NAIExporter;
+typedef struct _NAIExporterFileParms        NAIExporterFileParms;
+typedef struct _NAIExporterBufferParms      NAIExporterBufferParms;
+typedef struct _NAIExporterInterfacePrivate NAIExporterInterfacePrivate;
 
-typedef struct NAIExporterInterfacePrivate NAIExporterInterfacePrivate;
-
-/* When listing available export formats, the instance returns a GList
+/**
+ * NAIExporterFormat:
+ * @format:      format identifier (ascii).
+ * @label:       short label to be displayed in dialog (UTF-8 localized)
+ * @description: full description of the format (UTF-8 localized);
+ *               mainly used in the export assistant.
+ *
+ * This structure describes a supported output format.
+ * It must be implemented by each #NAIExporter implementation
+ * (see e.g. io-xml/naxml-formats.c).
+ *
+ * When listing available export formats, the instance returns a #GList
  * of these structures.
- * This structure must be implemented by each #NAIExporter implementation
- * (see e.g. io-xml/naxml-formats.c)
  */
 typedef struct {
-	gchar *format;					/* format identifier (ascii) */
-	gchar *label;					/* short label to be displayed in dialog (UTF-8 localized) */
-	gchar *description;				/* full description of the format (UTF-8 localized)
-									 * mainly used in the export assistant */
+	gchar *format;
+	gchar *label;
+	gchar *description;
 }
 	NAIExporterFormat;
 
+/**
+ * NAIExporterInterface:
+ * @get_version: returns the version of this interface the plugin implements.
+ * @get_name:    returns the public plugin name.
+ * @get_formats: returns the list of supported formats.
+ * @to_file:     exports an item to a file.
+ * @to_buffer:   exports an item to a buffer.
+ *
+ * This defines the interface that a #NAIExporter should implement.
+ */
 typedef struct {
+	/*< private >*/
 	GTypeInterface               parent;
 	NAIExporterInterfacePrivate *private;
 
+	/*< public >*/
 	/**
 	 * get_version:
 	 * @instance: this #NAIExporter instance.
@@ -140,42 +147,71 @@ typedef struct {
 }
 	NAIExporterInterface;
 
-/* The reasons for which an item may not have been exported
+/**
+ * NAIExporterExportStatus:
+ * @NA_IEXPORTER_CODE_OK:              export OK.
+ * @NA_IEXPORTER_CODE_INVALID_ITEM:    exported item was found invalid.
+ * @NA_IEXPORTER_CODE_INVALID_TARGET:  selected target was found invalid.
+ * @NA_IEXPORTER_CODE_INVALID_FORMAT:  asked format was found invalid.
+ * @NA_IEXPORTER_CODE_UNABLE_TO_WRITE: unable to write the item.
+ * @NA_IEXPORTER_CODE_ERROR:           other undetermined error.
+ *
+ * The reasons for which an item may not have been exported
  */
-enum {
+typedef enum {
 	NA_IEXPORTER_CODE_OK = 0,
 	NA_IEXPORTER_CODE_INVALID_ITEM,
 	NA_IEXPORTER_CODE_INVALID_TARGET,
 	NA_IEXPORTER_CODE_INVALID_FORMAT,
 	NA_IEXPORTER_CODE_UNABLE_TO_WRITE,
 	NA_IEXPORTER_CODE_ERROR,
-};
+}
+	NAIExporterExportStatus;
 
-/* parameters via a structure
- * ... when exporting to a file
+/**
+ * NAIExporterFileParms:
+ * @version:  version of this structure (input, since v 1)
+ * @exported: exported NAObjectItem-derived object (input, since v 1)
+ * @folder:   URI of the target folder (input, since v 1)
+ * @format:   export format as a GQuark (input, since v 1)
+ * @basename: basename of the exported file (output, since v 1)
+ * @messages: a #GSList list of localized strings;
+ *            the provider may append messages to this list,
+ *            but shouldn't reinitialize it
+ *            (input/output, since v 1).
+ *
+ * The structure that the plugin receives as a parameter of
+ * #NAIExporterInterface.to_file () interface method.
  */
-struct NAIExporterFileParms {
-	guint         version;				/* i 1: version of this structure */
-	NAObjectItem *exported;				/* i 1: exported NAObjectItem-derived object */
-	gchar        *folder;				/* i 1: URI of the target folder */
-	GQuark        format;				/* i 1: export format as a GQuark */
-	gchar        *basename;				/*  o1: basename of the exported file */
-	GSList       *messages;				/* io1: a #GSList list of localized strings;
-										 *       the provider may append messages to this list,
-										 *       but shouldn't reinitialize it. */
+struct _NAIExporterFileParms {
+	guint         version;
+	NAObjectItem *exported;
+	gchar        *folder;
+	GQuark        format;
+	gchar        *basename;
+	GSList       *messages;
 };
 
-/* parameters via a structure
- * ... when exporting to a buffer
+/**
+ * NAIExporterBufferParms:
+ * @version:  version of this structure (input, since v 1)
+ * @exported: exported NAObjectItem-derived object (input, since v 1)
+ * @format:   export format as a GQuark (input, since v 1)
+ * @buffer:   buffer which contains the exported object (output, since v 1)
+ * @messages: a #GSList list of localized strings;
+ *            the provider may append messages to this list,
+ *            but shouldn't reinitialize it
+ *            (input/output, since v 1).
+ *
+ * The structure that the plugin receives as a parameter of
+ * #NAIExporterInterface.to_buffer () interface method.
  */
-struct NAIExporterBufferParms {
-	guint         version;				/* i 1: version of this structure */
-	NAObjectItem *exported;				/* i 1: exported NAObjectItem-derived object */
-	GQuark        format;				/* i 1: export format as a GQuark */
-	gchar        *buffer;				/*  o1: buffer which contains the exported object */
-	GSList       *messages;				/* io1: a #GSList list of localized strings;
-										 *       the provider may append messages to this list,
-										 *       but shouldn't reinitialize it. */
+struct _NAIExporterBufferParms {
+	guint         version;
+	NAObjectItem *exported;
+	GQuark        format;
+	gchar        *buffer;
+	GSList       *messages;
 };
 
 GType na_iexporter_get_type( void );
diff --git a/src/api/na-iimporter.h b/src/api/na-iimporter.h
index a9889fd..0431fc4 100644
--- a/src/api/na-iimporter.h
+++ b/src/api/na-iimporter.h
@@ -43,6 +43,7 @@ G_BEGIN_DECLS
 typedef struct _NAIImporter                      NAIImporter;
 typedef struct _NAIImporterInterfacePrivate      NAIImporterInterfacePrivate;
 typedef struct _NAIImporterImportFromUriParms    NAIImporterImportFromUriParms;
+typedef struct _NAIImporterManageImportModeParms NAIImporterManageImportModeParms;
 
 /**
  * NAIImporterInterface:
@@ -94,12 +95,12 @@ typedef struct {
 /**
  * NAIImporterImportMode:
  * @IMPORTER_MODE_NO_IMPORT: a "do not import anything" mode.
- * @IMPORTER_MODE_RENUMBER: reallocate a new id when the imported one
- *  already exists.
- * @IMPORTER_MODE_OVERRIDE: override the existing id with the imported
- *  one.
- * @IMPORTER_MODE_ASK: ask the user for what to do with this particular
- *  item.
+ * @IMPORTER_MODE_RENUMBER:  reallocate a new id when the imported one
+ *                           already exists.
+ * @IMPORTER_MODE_OVERRIDE:  override the existing id with the imported
+ *                           one.
+ * @IMPORTER_MODE_ASK:       ask the user for what to do with this particular
+ *                           item.
  *
  * Define the mode of an import operation.
  */
@@ -113,16 +114,16 @@ typedef enum {
 
 /**
  * NAIImporterImportStatus:
- * @IMPORTER_CODE_OK: import ok.
- * @IMPORTER_CODE_PROGRAM_ERROR: a program error has been detected.
- *  You should open a bug in
- *  <ulink url="https://bugzilla.gnome.org/enter_bug.cgi?product=nautilus-actions";>Bugzilla</ulink>.
- * @IMPORTER_CODE_NOT_WILLING_TO: the plugin is not willing to import
- *  anything.
- * @IMPORTER_CODE_NO_ITEM_ID: item id not found.
- * @IMPORTER_CODE_NO_ITEM_TYPE: item type not found.
+ * @IMPORTER_CODE_OK:                import ok.
+ * @IMPORTER_CODE_PROGRAM_ERROR:     a program error has been detected.
+ *                                   You should open a bug in
+ *                                   <ulink url="https://bugzilla.gnome.org/enter_bug.cgi?product=nautilus-actions";>Bugzilla</ulink>.
+ * @IMPORTER_CODE_NOT_WILLING_TO:    the plugin is not willing to import
+ *                                   anything.
+ * @IMPORTER_CODE_NO_ITEM_ID:        item id not found.
+ * @IMPORTER_CODE_NO_ITEM_TYPE:      item type not found.
  * @IMPORTER_CODE_UNKNOWN_ITEM_TYPE: unknown item type.
- * @IMPORTER_CODE_CANCELLED: operation cancelled by the user.
+ * @IMPORTER_CODE_CANCELLED:         operation cancelled by the user.
  *
  * Define the return status of an import operation.
  */
@@ -271,7 +272,7 @@ struct _NAIImporterImportFromUriParms {
  *
  * Since: Nautilus-Actions v 2.30, NAIImporter interface v 1.
  */
-typedef struct {
+struct _NAIImporterManageImportModeParms {
 	guint                version;
 	NAObjectItem        *imported;
 	guint                asked_mode;
@@ -282,8 +283,7 @@ typedef struct {
 	gboolean             exist;
 	guint                import_mode;
 	GSList              *messages;
-}
-	NAIImporterManageImportModeParms;
+};
 
 GType na_iimporter_get_type( void );
 
diff --git a/src/api/na-iio-provider.h b/src/api/na-iio-provider.h
index 77948ed..d86f10b 100644
--- a/src/api/na-iio-provider.h
+++ b/src/api/na-iio-provider.h
@@ -270,21 +270,17 @@ void  na_iio_provider_item_changed ( const NAIIOProvider *instance );
  */
 /**
  * NAIIOProviderWritabilityStatus:
- * @NA_IIO_PROVIDER_STATUS_UNDETERMINED: undertermined.
- * @NA_IIO_PROVIDER_STATUS_WRITABLE: the item is writable.
- * @NA_IIO_PROVIDER_STATUS_ITEM_READONLY: the item is read-only.
- * @NA_IIO_PROVIDER_STATUS_PROVIDER_NOT_WILLING_TO: the provider is not
- *  willing to write this item, or doest not implement the required
- *  interface.
- * @NA_IIO_PROVIDER_STATUS_NO_PROVIDER_FOUND: the provider has not been
- *  found.
- * @NA_IIO_PROVIDER_STATUS_PROVIDER_LOCKED_BY_ADMIN: the provider has been
- *  locked by the administrator.
- * @NA_IIO_PROVIDER_STATUS_PROVIDER_LOCKED_BY_USER: the provider has been
- *  locked by the user.
- * @NA_IIO_PROVIDER_STATUS_CONFIGURATION_LOCKED_BY_ADMIN: the whole
- *  configuration has been locked by the administrator.
- * @NA_IIO_PROVIDER_STATUS_NO_API: no API has been found.
+ * @NA_IIO_PROVIDER_STATUS_UNDETERMINED:             undertermined.
+ * @NA_IIO_PROVIDER_STATUS_WRITABLE:                 the item is writable.
+ * @NA_IIO_PROVIDER_STATUS_ITEM_READONLY:            the item is read-only.
+ * @NA_IIO_PROVIDER_STATUS_PROVIDER_NOT_WILLING_TO:  the provider is not willing to write this item,
+ *                                                   or doest not implement the required interface.
+ * @NA_IIO_PROVIDER_STATUS_NO_PROVIDER_FOUND:        the provider has not been found.
+ * @NA_IIO_PROVIDER_STATUS_PROVIDER_LOCKED_BY_ADMIN: the provider has been locked by the administrator.
+ * @NA_IIO_PROVIDER_STATUS_PROVIDER_LOCKED_BY_USER:  the provider has been locked by the user.
+ * @NA_IIO_PROVIDER_STATUS_CONFIGURATION_LOCKED_BY_ADMIN: the whole configuration has been locked
+ *                                                        by the administrator.
+ * @NA_IIO_PROVIDER_STATUS_NO_API:                   no API has been found.
  *
  * The reasons for which an item may not be writable.
  */
@@ -308,17 +304,15 @@ typedef enum {
  */
 /**
  * NAIIOProviderOperationStatus:
- * @NA_IIO_PROVIDER_CODE_OK: the requested operation has been successful.
+ * @NA_IIO_PROVIDER_CODE_OK:            the requested operation has been successful.
  * @NA_IIO_PROVIDER_CODE_PROGRAM_ERROR: a program error has been detected.
- *  You should open a bug in
- *  <ulink url="https://bugzilla.gnome.org/enter_bug.cgi?product=nautilus-actions";>Bugzilla</ulink>.
- * @NA_IIO_PROVIDER_CODE_NOT_WILLING_TO_RUN: the provider is not willing
- *  to do the requested action.
- * @NA_IIO_PROVIDER_CODE_WRITE_ERROR: a write error has been detected.
- * @NA_IIO_PROVIDER_CODE_DELETE_SCHEMAS_ERROR: the schemas could not be
- *  deleted.
- * @NA_IIO_PROVIDER_CODE_DELETE_CONFIG_ERROR: the configuration could not
- *  be deleted.
+ *                                      You should open a bug in
+ *                                      <ulink url="https://bugzilla.gnome.org/enter_bug.cgi?product=nautilus-actions";>Bugzilla</ulink>.
+ * @NA_IIO_PROVIDER_CODE_NOT_WILLING_TO_RUN:   the provider is not willing
+ *                                             to do the requested action.
+ * @NA_IIO_PROVIDER_CODE_WRITE_ERROR:          a write error has been detected.
+ * @NA_IIO_PROVIDER_CODE_DELETE_SCHEMAS_ERROR: the schemas could not be deleted.
+ * @NA_IIO_PROVIDER_CODE_DELETE_CONFIG_ERROR:  the configuration could not be deleted.
  *
  * The return code of operations.
  */
diff --git a/src/core/na-exporter.c b/src/core/na-exporter.c
index 8955c63..718324e 100644
--- a/src/core/na-exporter.c
+++ b/src/core/na-exporter.c
@@ -44,7 +44,7 @@ static const NAIExporterFormat *exporter_get_formats( const NAIExporter *exporte
 static gchar                   *exporter_get_name( const NAIExporter *exporter );
 static NAIExporter             *find_exporter_for_format( const NAPivot *pivot, GQuark format );
 
-/**
+/*
  * na_exporter_get_formats:
  * @pivot: the #NAPivot instance.
  *
@@ -86,7 +86,7 @@ na_exporter_get_formats( const NAPivot *pivot )
 	return( formats );
 }
 
-/**
+/*
  * na_exporter_free_formats:
  * @formats: a list of available export formats, as returned by
  *  #na_exporter_get_formats().
@@ -100,7 +100,7 @@ na_exporter_free_formats( GList *formats )
 	g_list_free( formats );
 }
 
-/**
+/*
  * na_exporter_to_buffer:
  * @pivot: the #NAPivot pivot for the running application.
  * @item: a #NAObjectItem-derived object.
@@ -171,7 +171,7 @@ na_exporter_to_buffer( const NAPivot *pivot, const NAObjectItem *item, GQuark fo
 	return( buffer );
 }
 
-/**
+/*
  * na_exporter_to_file:
  * @pivot: the #NAPivot pivot for the running application.
  * @item: a #NAObjectItem-derived object.
diff --git a/src/core/na-exporter.h b/src/core/na-exporter.h
index 9a7efd5..6c10297 100644
--- a/src/core/na-exporter.h
+++ b/src/core/na-exporter.h
@@ -31,7 +31,7 @@
 #ifndef __CORE_NA_EXPORTER_H__
 #define __CORE_NA_EXPORTER_H__
 
-/**
+/*
  * SECTION: na_iexporter
  * @short_description: #NAIExporter internal functions.
  * @include: core/na-exporter.h
diff --git a/src/core/na-iexporter.c b/src/core/na-iexporter.c
index edf8c3c..3d552aa 100644
--- a/src/core/na-iexporter.c
+++ b/src/core/na-iexporter.c
@@ -34,9 +34,44 @@
 
 #include <api/na-iexporter.h>
 
+/**
+ * SECTION: iexporter
+ * @title: NAIExporter
+ * @short_description: The Export Interface
+ * @include: nautilus-actions/na-iexporter.h
+ *
+ * The #NAIExporter interface exports items to the outside world.
+ *
+ * <refsect2>
+ *  <title>Versions historic</title>
+ *  <table>
+ *    <title>Historic of the versions of the #NAIExporter 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>#NAIExporter 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 NAIExporterInterfacePrivate {
+struct _NAIExporterInterfacePrivate {
 	void *empty;						/* so that gcc -pedantic is happy */
 };
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]