[nautilus-actions] Reference manual: fix NAIImporter documentation

From: Pierre Wieser <pwieser src gnome org>
To: commits-list gnome org
Cc:
Subject: [nautilus-actions] Reference manual: fix NAIImporter documentation
Date: Thu, 9 Dec 2010 23:10:24 +0000 (UTC)
commit 8d471e2c4333419ca8df63b37c445bc5a4c0cdc5
Author: Pierre Wieser <pwieser trychlos org>
Date:   Thu Dec 9 19:28:28 2010 +0100

    Reference manual: fix NAIImporter documentation

 ChangeLog                                     |   17 ++++
 docs/reference/.gitignore                     |    1 -
 docs/reference/nautilus-actions-overrides.txt |   17 ++++
 docs/reference/nautilus-actions-sections.txt  |   44 +++++----
 src/api/na-iimporter.h                        |  121 +++++++++++++++++--------
 src/api/na-iio-provider.h                     |   26 +++---
 src/core/na-iimporter.c                       |   77 ++++++++++++++--
 src/core/na-iio-provider.c                    |    2 +-
 src/core/na-importer-ask.c                    |    2 +-
 src/core/na-importer-ask.h                    |    7 +-
 src/core/na-importer.c                        |    4 +-
 src/core/na-importer.h                        |   11 ++-
 12 files changed, 238 insertions(+), 91 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 5438c7e..97b5d57 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,20 @@
+2010-12-09 Pierre Wieser <pwieser trychlos org>
+
+	Fix NAIImporter reference manual.
+
+	* docs/reference/.gitignore:
+	* docs/reference/nautilus-actions-sections.txt:
+	* src/api/na-iimporter.h:
+	* src/api/na-iio-provider.h:
+	* src/core/na-iimporter.c:
+	* src/core/na-iio-provider.c:
+	* src/core/na-importer-ask.c:
+	* src/core/na-importer-ask.h:
+	* src/core/na-importer.c:
+	* src/core/na-importer.h: Updated accordingly.
+
+	* docs/reference/nautilus-actions-sections.txt: New file.
+
 2010-12-08 Pierre Wieser <pwieser trychlos org>
 
 	Update reference manual for extensions.
diff --git a/docs/reference/.gitignore b/docs/reference/.gitignore
index 3b9d7c4..6c1d09a 100644
--- a/docs/reference/.gitignore
+++ b/docs/reference/.gitignore
@@ -2,7 +2,6 @@ html/
 tmpl/
 xml/
 *-decl*
-*-overrides.txt
 *-undeclared.txt
 *-undocumented.txt
 *-unused.txt
diff --git a/docs/reference/nautilus-actions-overrides.txt b/docs/reference/nautilus-actions-overrides.txt
new file mode 100644
index 0000000..c3af109
--- /dev/null
+++ b/docs/reference/nautilus-actions-overrides.txt
@@ -0,0 +1,17 @@
+# pwi 2010-12- 9 it appears that gtk-doc does not deal correctly with functions typedef :(
+#                so forcing them here
+
+<FUNCTION>
+<NAME>NAIImporterCheckFn</NAME>
+<RETURNS>NAObjectItem *</RETURNS>
+ const NAObjectItem *imported
+ void *fn_data 
+</FUNCTION>
+
+<FUNCTION>
+<NAME>NAIImporterAskUserFn</NAME>
+<RETURNS>guint</RETURNS>
+ const NAObjectItem *imported
+ const NAObjectItem *existing
+ void *fn_data 
+</FUNCTION>
diff --git a/docs/reference/nautilus-actions-sections.txt b/docs/reference/nautilus-actions-sections.txt
index a13e440..ba6c875 100644
--- a/docs/reference/nautilus-actions-sections.txt
+++ b/docs/reference/nautilus-actions-sections.txt
@@ -20,10 +20,34 @@ NAIIOProviderOperationStatus
 na_iio_provider_item_changed
 
 <SUBSECTION Standard>
+na_iio_provider_get_type
 
 <SUBSECTION Private>
 NAIIOProviderInterfacePrivate
-na_iio_provider_get_type
+</SECTION>
+
+<SECTION>
+<FILE>iimporter</FILE>
+NA_IIMPORTER_TYPE
+NA_IIMPORTER
+NA_IS_IIMPORTER
+NA_IIMPORTER_GET_INTERFACE
+NAIImporter
+NAIImporterInterface
+NAIImporterImportFromUriParms
+NAIImporterManageImportModeParms
+NAIImporterCheckFn
+NAIImporterAskUserFn
+NAIImporterImportMode
+NAIImporterImportStatus
+na_iimporter_import_from_uri
+na_iimporter_manage_import_mode
+
+<SUBSECTION Standard>
+na_iimporter_get_type
+
+<SUBSECTION Private>
+NAIImporterInterfacePrivate
 </SECTION>
 
 <SECTION>
@@ -60,24 +84,6 @@ na_ifactory_provider_get_type
 </SECTION>
 
 <SECTION>
-<FILE>iimporter</FILE>
-NA_IIMPORTER_TYPE
-NA_IIMPORTER_GET_INTERFACE
-NAIImporter
-NAIImporterInterfacePrivate
-NAIImporterImportFromUriParms
-NAIImporterManageImportModeParms
-NAIImporterInterface
-na_iimporter_import_from_uri
-na_iimporter_manage_import_mode
-
-<SUBSECTION Standard>
-NA_IIMPORTER
-NA_IS_IIMPORTER
-na_iimporter_get_type
-</SECTION>
-
-<SECTION>
 <FILE>iexporter</FILE>
 NA_IEXPORTER_TYPE
 NA_IEXPORTER_GET_INTERFACE
diff --git a/src/api/na-iimporter.h b/src/api/na-iimporter.h
index 876099b..a9889fd 100644
--- a/src/api/na-iimporter.h
+++ b/src/api/na-iimporter.h
@@ -31,44 +31,48 @@
 #ifndef __NAUTILUS_ACTIONS_API_NA_IIMPORTER_H__
 #define __NAUTILUS_ACTIONS_API_NA_IIMPORTER_H__
 
-/**
- * SECTION: iimporter
- * @section_id: iimporter
- * @title: NAIImporter (na-iimporter.h title)
- * @short_description: #NAIImporter interface definition (na-iimporter.h short description)
- * @include: nautilus-actions/na-iimporter.h
- *
- * The #NAIImporter interface imports items from the outside world.
- *
- * Since: Nautilus-Actions v 2.30 (API version 1)
- */
-
 #include "na-object-item.h"
 
 G_BEGIN_DECLS
 
-#define NA_IIMPORTER_TYPE						( na_iimporter_get_type())
-#define NA_IIMPORTER( instance )				( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_IIMPORTER_TYPE, NAIImporter ))
-#define NA_IS_IIMPORTER( instance )				( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_IIMPORTER_TYPE ))
-#define NA_IIMPORTER_GET_INTERFACE( instance )	( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_IIMPORTER_TYPE, NAIImporterInterface ))
-
-typedef struct NAIImporter                      NAIImporter;
-typedef struct NAIImporterInterfacePrivate      NAIImporterInterfacePrivate;
+#define NA_IIMPORTER_TYPE                       ( na_iimporter_get_type())
+#define NA_IIMPORTER( instance )                ( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_IIMPORTER_TYPE, NAIImporter ))
+#define NA_IS_IIMPORTER( instance )             ( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_IIMPORTER_TYPE ))
+#define NA_IIMPORTER_GET_INTERFACE( instance )  ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_IIMPORTER_TYPE, NAIImporterInterface ))
 
-typedef struct NAIImporterImportFromUriParms    NAIImporterImportFromUriParms;
-typedef struct NAIImporterManageImportModeParms NAIImporterManageImportModeParms;
+typedef struct _NAIImporter                      NAIImporter;
+typedef struct _NAIImporterInterfacePrivate      NAIImporterInterfacePrivate;
+typedef struct _NAIImporterImportFromUriParms    NAIImporterImportFromUriParms;
 
+/**
+ * NAIImporterInterface:
+ * @get_version:     returns the version of this interface that the
+ *                   plugin implements.
+ * @import_from_uri: imports an item.
+ *
+ * This defines the interface that a #NAIImporter should implement.
+ */
 typedef struct {
+	/*< private >*/
 	GTypeInterface               parent;
 	NAIImporterInterfacePrivate *private;
 
+	/*< public >*/
 	/**
 	 * get_version:
 	 * @instance: the #NAIImporter provider.
 	 *
-	 * Returns: the version of this interface supported by the I/O provider.
+	 * This method is called by the &prodname; program each time
+	 * it needs to know which version of this interface the plugin
+	 * implements.
+	 *
+	 * If this method is not implemented by the plugin,
+	 * the &prodname; program considers that the plugin only implements
+	 * the version 1 of the #NAIImporter interface.
 	 *
-	 * Defaults to 1.
+	 * Returns: the version of this interface supported by the plugin.
+	 *
+	 * Since: Nautilus-Actions v 2.30, NAIImporter interface v 1.
 	 */
 	guint ( *get_version )    ( const NAIImporter *instance );
 
@@ -80,23 +84,49 @@ typedef struct {
 	 * Imports an item.
 	 *
 	 * Returns: the return code of the operation.
+	 *
+	 * Since: Nautilus-Actions v 2.30, NAIImporter interface v 1.
 	 */
 	guint ( *import_from_uri )( const NAIImporter *instance, NAIImporterImportFromUriParms *parms );
 }
 	NAIImporterInterface;
 
-/* import mode
+/**
+ * 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.
+ *
+ * Define the mode of an import operation.
  */
-enum {
-	IMPORTER_MODE_NO_IMPORT = 1,		/* this is a "do not import anything" mode */
+typedef enum {
+	IMPORTER_MODE_NO_IMPORT = 1,
 	IMPORTER_MODE_RENUMBER,
 	IMPORTER_MODE_OVERRIDE,
 	IMPORTER_MODE_ASK
-};
+}
+	NAIImporterImportMode;
 
-/* return code
+/**
+ * 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_UNKNOWN_ITEM_TYPE: unknown item type.
+ * @IMPORTER_CODE_CANCELLED: operation cancelled by the user.
+ *
+ * Define the return status of an import operation.
  */
-enum {
+typedef enum {
 	IMPORTER_CODE_OK = 0,
 	IMPORTER_CODE_PROGRAM_ERROR,
 	IMPORTER_CODE_NOT_WILLING_TO,
@@ -104,11 +134,12 @@ enum {
 	IMPORTER_CODE_NO_ITEM_TYPE,
 	IMPORTER_CODE_UNKNOWN_ITEM_TYPE,
 	IMPORTER_CODE_CANCELLED
-};
+}
+	NAIImporterImportStatus;
 
 /**
  * NAIImporterCheckFn:
- * @imported: the currently imported #NAObjectItem.
+ * @imported: the currently imported #NAObjectItem -derived object.
  * @fn_data: some data to be passed to the function.
  *
  * This function may be provided by the caller in order the #NAIImporter
@@ -123,6 +154,8 @@ enum {
  * the asked import mode.
  *
  * Returns: the already existing #NAObjectItem with same id, or %NULL.
+ *
+ * Since: Nautilus-Actions v 2.30, NAIImporter interface v 1.
  */
 typedef NAObjectItem * ( *NAIImporterCheckFn )( const NAObjectItem *, void * );
 
@@ -140,7 +173,10 @@ typedef NAObjectItem * ( *NAIImporterCheckFn )( const NAObjectItem *, void * );
  * not be able to ask the user. In this case, the duplicated id should be
  * systematically regenerated as a unique id (uuid).
  *
- * Returns: the import mode choosen by the user, which must not be %ASK.
+ * Returns: the import mode choosen by the user, which must not be
+ * %IMPORTER_MODE_ASK.
+ *
+ * Since: Nautilus-Actions v 2.30, NAIImporter interface v 1.
  */
 typedef guint ( *NAIImporterAskUserFn )( const NAObjectItem *, const NAObjectItem *, void * );
 
@@ -161,16 +197,16 @@ typedef guint ( *NAIImporterAskUserFn )( const NAObjectItem *, const NAObjectIte
  * @import_mode:   actually used import mode.
  *                 output;
  *                 since version 1 of the structure.
- * @imported:      the imported NAObjectItem-derived object, or %NULL.
+ * @imported:      the imported #NAObjectItem -derived object, or %NULL.
  *                 output;
  *                 since version 1 of the structure.
- * @check_fn:      a #NAIImporterCheckFn function to check the existence of the imported id.
+ * @check_fn:      a NAIImporterCheckFn() function to check the existence of the imported id.
  *                 input;
  *                 since version 1 of the structure.
  * @check_fn_data: @check_fn data
  *                 input;
  *                 since version 1 of the structure.
- * @ask_fn:        a #NAIImporterAskUserFn function to ask the user what to do in case of a duplicate id
+ * @ask_fn:        a NAIImporterAskUserFn() function to ask the user what to do in case of a duplicate id
  *                 input;
  *                 since version 1 of the structure.
  * @ask_fn_data:   @ask_fn data
@@ -183,8 +219,10 @@ typedef guint ( *NAIImporterAskUserFn )( const NAObjectItem *, const NAObjectIte
  *
  * This structure allows all used parameters when importing from an URI
  * to be passed and received through a single structure.
+ *
+ * Since: Nautilus-Actions v 2.30, NAIImporter interface v 1.
  */
-struct NAIImporterImportFromUriParms {
+struct _NAIImporterImportFromUriParms {
 	guint                version;
 	gchar               *uri;
 	guint                asked_mode;
@@ -198,12 +236,12 @@ struct NAIImporterImportFromUriParms {
 	GSList              *messages;
 };
 
-/*
+/**
  * NAIImporterManageImportModeParms:
  * @version:       the version of this structure, currently equals to 1.
  *                 input;
  *                 since version 1 of the structure.
- * @imported:      the imported #NAObjectItem-derived object
+ * @imported:      the imported #NAObjectItem -derived object
  * @asked_mode:    asked import mode
  * @check_fn:      a #NAIImporterCheckFn function to check the existence of the imported id.
  *                 input;
@@ -230,8 +268,10 @@ struct NAIImporterImportFromUriParms {
  *
  * This structure allows all used parameters when managing the import mode
  * to be passed and received through a single structure.
+ *
+ * Since: Nautilus-Actions v 2.30, NAIImporter interface v 1.
  */
-struct NAIImporterManageImportModeParms {
+typedef struct {
 	guint                version;
 	NAObjectItem        *imported;
 	guint                asked_mode;
@@ -242,7 +282,8 @@ struct NAIImporterManageImportModeParms {
 	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 cde5b33..77948ed 100644
--- a/src/api/na-iio-provider.h
+++ b/src/api/na-iio-provider.h
@@ -35,10 +35,10 @@
 
 G_BEGIN_DECLS
 
-#define NA_IIO_PROVIDER_TYPE						( na_iio_provider_get_type())
-#define NA_IIO_PROVIDER( instance )					( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_IIO_PROVIDER_TYPE, NAIIOProvider ))
-#define NA_IS_IIO_PROVIDER( instance )				( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_IIO_PROVIDER_TYPE ))
-#define NA_IIO_PROVIDER_GET_INTERFACE( instance )	( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_IIO_PROVIDER_TYPE, NAIIOProviderInterface ))
+#define NA_IIO_PROVIDER_TYPE                        ( na_iio_provider_get_type())
+#define NA_IIO_PROVIDER( instance )                 ( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_IIO_PROVIDER_TYPE, NAIIOProvider ))
+#define NA_IS_IIO_PROVIDER( instance )              ( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_IIO_PROVIDER_TYPE ))
+#define NA_IIO_PROVIDER_GET_INTERFACE( instance )   ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_IIO_PROVIDER_TYPE, NAIIOProviderInterface ))
 
 typedef struct _NAIIOProvider                 NAIIOProvider;
 
@@ -79,7 +79,7 @@ typedef struct {
 	 *
 	 * Returns: the version of this interface supported by the I/O provider.
 	 *
-	 * Since: Nautilus-Actions v 2.30, #NAIIOProvider interface v 1.
+	 * Since: Nautilus-Actions v 2.30, NAIIOProvider interface v 1.
 	 */
 	guint    ( *get_version )        ( const NAIIOProvider *instance );
 
@@ -97,7 +97,7 @@ typedef struct {
 	 * Returns: the id of the I/O provider, as a newly allocated string
 	 * which should be g_free() by the caller.
 	 *
-	 * Since: Nautilus-Actions v 2.30, #NAIIOProvider interface v 1.
+	 * Since: Nautilus-Actions v 2.30, NAIIOProvider interface v 1.
 	 */
 	gchar *  ( *get_id )             ( const NAIIOProvider *instance );
 
@@ -110,7 +110,7 @@ typedef struct {
 	 * Returns: the name to be displayed for this I/O provider, as a
 	 * newly allocated string which should be g_free() by the caller.
 	 *
-	 * Since: Nautilus-Actions v 2.30, #NAIIOProvider interface v 1.
+	 * Since: Nautilus-Actions v 2.30, NAIIOProvider interface v 1.
 	 */
 	gchar *  ( *get_name )           ( const NAIIOProvider *instance );
 
@@ -127,7 +127,7 @@ typedef struct {
 	 * Returns: a unordered flat #GList of #NAObjectItem -derived objects
 	 * (menus or actions); the actions embed their own profiles.
 	 *
-	 * Since: Nautilus-Actions v 2.30, #NAIIOProvider interface v 1.
+	 * Since: Nautilus-Actions v 2.30, NAIIOProvider interface v 1.
 	 */
 	GList *  ( *read_items )         ( const NAIIOProvider *instance, GSList **messages );
 
@@ -151,7 +151,7 @@ typedef struct {
 	 * Returns: %TRUE if this I/O provider is willing to write,
 	 *  %FALSE else.
 	 *
-	 * Since: Nautilus-Actions v 2.30, #NAIIOProvider interface v 1.
+	 * Since: Nautilus-Actions v 2.30, NAIIOProvider interface v 1.
 	 */
 	gboolean ( *is_willing_to_write )( const NAIIOProvider *instance );
 
@@ -183,7 +183,7 @@ typedef struct {
 	 * Returns: %TRUE if this I/O provider is able to do write
 	 * operations at runtime, %FALSE else.
 	 *
-	 * Since: Nautilus-Actions v 2.30, #NAIIOProvider interface v 1.
+	 * Since: Nautilus-Actions v 2.30, NAIIOProvider interface v 1.
 	 */
 	gboolean ( *is_able_to_write )   ( const NAIIOProvider *instance );
 
@@ -206,7 +206,7 @@ typedef struct {
 	 * Returns: %NA_IIO_PROVIDER_CODE_OK if the write operation
 	 * was successfull, or another code depending of the detected error.
 	 *
-	 * Since: Nautilus-Actions v 2.30, #NAIIOProvider interface v 1.
+	 * Since: Nautilus-Actions v 2.30, NAIIOProvider interface v 1.
 	 */
 	guint    ( *write_item )         ( const NAIIOProvider *instance, const NAObjectItem *item, GSList **messages );
 
@@ -225,7 +225,7 @@ typedef struct {
 	 * Returns: %NA_IIO_PROVIDER_CODE_OK if the delete operation was
 	 * successfull, or another code depending of the detected error.
 	 *
-	 * Since: Nautilus-Actions v 2.30, #NAIIOProvider interface v 1.
+	 * Since: Nautilus-Actions v 2.30, NAIIOProvider interface v 1.
 	 */
 	guint    ( *delete_item )        ( const NAIIOProvider *instance, const NAObjectItem *item, GSList **messages );
 
@@ -246,7 +246,7 @@ typedef struct {
 	 * Returns: %NA_IIO_PROVIDER_CODE_OK if the duplicate operation was
 	 * successfull, or another code depending of the detected error.
 	 *
-	 * Since: Nautilus-Actions v 2.30, #NAIIOProvider interface v 1.
+	 * Since: Nautilus-Actions v 2.30, NAIIOProvider interface v 1.
 	 */
 	guint    ( *duplicate_data )     ( const NAIIOProvider *instance, NAObjectItem *dest, const NAObjectItem *source, GSList **messages );
 }
diff --git a/src/core/na-iimporter.c b/src/core/na-iimporter.c
index 482881b..c1c86ed 100644
--- a/src/core/na-iimporter.c
+++ b/src/core/na-iimporter.c
@@ -38,9 +38,44 @@
 #include <api/na-iimporter.h>
 #include <api/na-object-api.h>
 
+/**
+ * SECTION: iimporter
+ * @title: NAIImporter
+ * @short_description: The Import Interface
+ * @include: nautilus-actions/na-iimporter.h
+ *
+ * The #NAIImporter interface imports items from the outside world.
+ *
+ * <refsect2>
+ *  <title>Versions historic</title>
+ *  <table>
+ *    <title>Historic of the versions of the #NAIImporter 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>#NAIImporter 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 NAIImporterInterfacePrivate {
+struct _NAIImporterInterfacePrivate {
 	void *empty;						/* so that gcc -pedantic is happy */
 };
 
@@ -149,9 +184,11 @@ iimporter_get_version( const NAIImporter *instance )
  * @parms: a #NAIImporterImportFromUriParms structure.
  *
  * Tries to import a #NAObjectItem from the URI specified in @parms, returning
- * the result in @parms->imported.
+ * the result in <structfield>@parms->imported</structfield>.
  *
  * Returns: the return code of the operation.
+ *
+ * Since: Nautilus-Actions v 2.30, NAIImporter interface v 1.
  */
 
 guint
@@ -176,13 +213,37 @@ na_iimporter_import_from_uri( const NAIImporter *importer, NAIImporterImportFrom
 	return( code );
 }
 
-/*
- * Returns IMPORTER_CODE_OK if we can safely insert the action
- * - the id doesn't already exist
- * - the id already exist, but import mode is renumber
- * - the id already exists, but import mode is override
+/**
+ * na_iimporter_manage_import_mode:
+ * @parms: a NAIImporterManageImportModeParms struct.
+ *
+ * Returns: the #NAIImporterImportStatus status of the operation:
+ *
+ * <itemizedlist>
+ *   <listitem>
+ *     <para>
+ *       IMPORTER_CODE_OK if we can safely insert the action:
+ *     </para>
+ *     <itemizedlist>
+ *       <listitem>
+ *         <para>the id doesn't already exist</para>
+ *       </listitem>
+ *       <listitem>
+ *         <para>the id already exist, but import mode is renumber</para>
+ *       </listitem>
+ *       <listitem>
+ *         <para>the id already exists, but import mode is override</para>
+ *       </listitem>
+ *     </itemizedlist>
+ *   </listitem>
+ *   <listitem>
+ *     <para>
+ *       IMPORTER_CODE_CANCELLED if user chooses to cancel the operation
+ *     </para>
+ *   </listitem>
+ * </itemizedlist>
  *
- * Returns IMPORTER_CODE_CANCELLED if user chooses to cancel the operation
+ * Since: Nautilus-Actions v 2.30, NAIImporter interface v 1.
  */
 guint
 na_iimporter_manage_import_mode( NAIImporterManageImportModeParms *parms )
diff --git a/src/core/na-iio-provider.c b/src/core/na-iio-provider.c
index 1622e03..7d41d5a 100644
--- a/src/core/na-iio-provider.c
+++ b/src/core/na-iio-provider.c
@@ -261,7 +261,7 @@ do_is_able_to_write( const NAIIOProvider *instance )
  * actions, or ask the user if he is willing to reload such a current
  * list, depending of the exact running &prodname; program.
  *
- * Since: Nautilus-Actions v 2.30, #NAIIOProvider interface v 1.
+ * Since: Nautilus-Actions v 2.30, NAIIOProvider interface v 1.
  */
 void
 na_iio_provider_item_changed( const NAIIOProvider *instance )
diff --git a/src/core/na-importer-ask.c b/src/core/na-importer-ask.c
index 85a6175..333fa0d 100644
--- a/src/core/na-importer-ask.c
+++ b/src/core/na-importer-ask.c
@@ -222,7 +222,7 @@ import_ask_new()
 	return( g_object_new( NA_IMPORTER_ASK_TYPE, NULL ));
 }
 
-/**
+/*
  * na_importer_ask_user:
  * @importing: the #NAObjectItem-derived object being currently imported.
  * @existing: the #NAObjectItem-derived already existing object with the same ID.
diff --git a/src/core/na-importer-ask.h b/src/core/na-importer-ask.h
index 15f2362..ab08593 100644
--- a/src/core/na-importer-ask.h
+++ b/src/core/na-importer-ask.h
@@ -31,9 +31,10 @@
 #ifndef __CORE_NA_IMPORTER_ASK_H__
 #define __CORE_NA_IMPORTER_ASK_H__
 
-/**
- * SECTION: na_importer_ask
- * @short_description: #NAImporterAsk class definition.
+/*
+ * SECTION: importer-ask
+ * @title: NAImporterAsk
+ * @short_description: The #NAImporterAsk class definition.
  * @include: core/na-iimporter-ask.h
  *
  * This class reates and manages a dialog. It is ran each time an
diff --git a/src/core/na-importer.c b/src/core/na-importer.c
index 5a8c0b1..0abda8e 100644
--- a/src/core/na-importer.c
+++ b/src/core/na-importer.c
@@ -55,7 +55,7 @@ static guint         import_from_uri( const NAPivot *pivot, GList *modules, NAIm
 static NAObjectItem *is_importing_already_exists( const NAObjectItem *importing, ImporterExistsStr *parms );
 static guint         ask_user_for_mode( const NAObjectItem *importing, const NAObjectItem *existing, NAImporterAskUserParms *parms );
 
-/**
+/*
  * na_importer_import_from_list:
  * @pivot: the #NAPivot pivot for this application.
  * @parms: a #NAImporterParms structure.
@@ -116,7 +116,7 @@ na_importer_import_from_list( const NAPivot *pivot, NAImporterParms *parms )
 	return( code );
 }
 
-/**
+/*
  * na_importer_free_result:
  * @result: the #NAImporterResult structure to be released.
  *
diff --git a/src/core/na-importer.h b/src/core/na-importer.h
index dfb3a9a..d432590 100644
--- a/src/core/na-importer.h
+++ b/src/core/na-importer.h
@@ -31,10 +31,15 @@
 #ifndef __CORE_NA_IMPORTER_H__
 #define __CORE_NA_IMPORTER_H__
 
-/**
- * SECTION: na_iimporter
- * @short_description: #NAIImporter internal functions.
+/*
+ * SECTION: iimporter
+ * @title: NAIImporter
+ * @short_description: The NAIImporter internal functions.
  * @include: core/na-importer.h
+ *
+ * Internal Nautilus-Actions code should never directly call a
+ * #NAIImporter interface method, but rather should call the
+ * corresponding na_importer_xxx() function.
  */
 
 #include <gtk/gtk.h>
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]