Commit b9cfa7c7 authored by Pierre Wieser's avatar Pierre Wieser

Reference manual: Fix NAObject documentation

parent 5c3b8e6d
2010-12-11 Pierre Wieser <pwieser@trychlos.org>
Fix NAObject documentation.
* docs/reference/nautilus-actions-docs.xml
* docs/reference/nautilus-actions-sections.txt:
* src/api/na-data-boxed.h:
* src/api/na-data-def.h:
* src/api/na-data-types.h:
* src/api/na-iexporter.h:
* src/api/na-ifactory-object.h:
* src/api/na-ifactory-provider.h:
* src/api/na-iimporter.h:
* src/api/na-iio-provider.h:
* src/api/na-object.h:
* src/core/na-data-boxed.c:
* src/core/na-data-def.c:
* src/core/na-data-types.c:
* src/core/na-export-format.c:
* src/core/na-export-format.h:
* src/core/na-exporter.h:
* src/core/na-factory-object.h:
* src/core/na-factory-provider.c:
* src/core/na-factory-provider.h:
* src/core/na-gnome-vfs-uri.c:
* src/core/na-gnome-vfs-uri.h:
* src/core/na-gtk-utils.c:
* src/core/na-gtk-utils.h:
* src/core/na-iabout.c:
* src/core/na-iabout.h:
* src/core/na-iexporter.c:
* src/core/na-ifactory-object.c:
* src/core/na-ifactory-provider.c:
* 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.h:
* src/core/na-io-provider.c:
* src/core/na-io-provider.h:
* src/core/na-ipivot-consumer.c:
* src/core/na-ipivot-consumer.h:
* src/core/na-iprefs.c:
* src/core/na-iprefs.h:
* src/core/na-module.c:
* src/core/na-module.h:
* src/core/na-object.c:
* src/core/na-pivot.c:
* src/core/na-pivot.h:
* src/core/na-selected-info.c:
* src/core/na-selected-info.h:
* src/core/na-tokens.c:
* src/core/na-tokens.h:
* src/core/na-updater.c:
* src/core/na-updater.h: Updated accordingly.
Fix D-Bus Services documentation.
* docs/reference/nautilus-actions-docs.xml:
......
......@@ -68,19 +68,23 @@
</chapter>
<chapter>
<title>Others (nautilus-actions-api.xml title)</title>
<title>NAObject Hierarchy</title>
<xi:include href="xml/object.xml"/>
<xi:include href="xml/na-object-id.xml"/>
<xi:include href="xml/na-object-action.xml"/>
<xi:include href="xml/na-icontext.xml"/>
<xi:include href="xml/na-gconf-monitor.xml"/>
<xi:include href="xml/na-object-menu.xml"/>
<xi:include href="xml/na-object-item.xml"/>
<xi:include href="xml/na-object.xml"/>
<xi:include href="xml/na-object-action.xml"/>
<xi:include href="xml/na-object-profile.xml"/>
<xi:include href="xml/na-object-menu.xml"/>
<xi:include href="xml/na-iduplicable.xml"/>
<xi:include href="xml/na-icontext.xml"/>
<xi:include href="xml/na-object-api.xml"/>
</chapter>
<chapter>
<title>Miscellaneous API</title>
<xi:include href="xml/na-gconf-monitor.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"/>
</chapter>
<chapter id="object-tree">
......
......@@ -262,11 +262,11 @@ NAFO_DATA_CAPABILITITES
<SECTION>
<FILE>object</FILE>
<TITLE>NAObject</TITLE>
NA_OBJECT_TYPE
NAObjectPrivate
NAObjectClassPrivate
NA_OBJECT
NA_IS_OBJECT
NAObject
NAObjectClass
na_object_object_check_status
na_object_object_check_status_up
na_object_object_reset_origin
......@@ -281,12 +281,14 @@ na_object_free_hierarchy
na_object_object_debug_invalid
<SUBSECTION Standard>
NA_OBJECT
NA_IS_OBJECT
na_object_object_get_type
NA_OBJECT_CLASS
NA_IS_OBJECT_CLASS
NA_OBJECT_GET_CLASS
<SUBSECTION Private>
NAObjectPrivate
NAObjectClassPrivate
</SECTION>
<SECTION>
......
......@@ -31,6 +31,42 @@
#ifndef __NAUTILUS_ACTIONS_API_NA_DATA_BOXED_H__
#define __NAUTILUS_ACTIONS_API_NA_DATA_BOXED_H__
/**
* SECTION: data-boxed
* @title: NADataBoxed
* @short_description: The Data Factory Element 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>
*/
#include <glib-object.h>
#include "na-data-def.h"
......@@ -56,6 +92,7 @@ typedef struct {
typedef struct NADataBoxedClassPrivate NADataBoxedClassPrivate;
typedef struct {
/*< private >*/
GObjectClass parent;
NADataBoxedClassPrivate *private;
}
......
......@@ -31,6 +31,17 @@
#ifndef __NAUTILUS_ACTIONS_API_NA_FACTORY_DATA_DEF_H__
#define __NAUTILUS_ACTIONS_API_NA_FACTORY_DATA_DEF_H__
/**
* SECTION: data-def
* @title: NADataDef, NADataGroup
* @short_description: The Data Factory Structure Definitions
* @include: nautilus-actions/na-data-def.h
*
* #NADataDef and #NADataGroup are structures which handle the list of
* elementary datas for each and every #NAObjectItem which happens to
* implement the #NAIFactoryObject interface.
*/
#include <glib.h>
G_BEGIN_DECLS
......
......@@ -31,6 +31,13 @@
#ifndef __NAUTILUS_ACTIONS_API_NA_FACTORY_DATA_TYPES_H__
#define __NAUTILUS_ACTIONS_API_NA_FACTORY_DATA_TYPES_H__
/**
* SECTION: data-type
* @title: NADataType
* @short_description: The Data Factory Type Definitions
* @include: nautilus-actions/na-data-types.h
*/
#include <glib.h>
G_BEGIN_DECLS
......
......@@ -31,6 +31,41 @@
#ifndef __NAUTILUS_ACTIONS_API_NA_IEXPORTER_H__
#define __NAUTILUS_ACTIONS_API_NA_IEXPORTER_H__
/**
* SECTION: iexporter
* @title: NAIExporter
* @short_description: The Export Interface v 1
* @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>
*/
#include "na-object-item.h"
G_BEGIN_DECLS
......
......@@ -31,6 +31,52 @@
#ifndef __NAUTILUS_ACTIONS_API_NA_IFACTORY_OBJECT_H__
#define __NAUTILUS_ACTIONS_API_NA_IFACTORY_OBJECT_H__
/**
* SECTION: ifactory-object
* @title: NAIFactoryObject
* @short_description: The #NAObjectItem Interface v 1
* @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>
*/
#include "na-data-def.h"
#include "na-data-boxed.h"
#include "na-ifactory-provider-provider.h"
......
......@@ -31,6 +31,110 @@
#ifndef __NAUTILUS_ACTIONS_API_NA_IFACTORY_PROVIDER_H__
#define __NAUTILUS_ACTIONS_API_NA_IFACTORY_PROVIDER_H__
/**
* SECTION: ifactory-provider
* @title: NAIFactoryProvider
* @short_description: The Data Factory Provider Interface v 1
* @include: nautilus-actions/na-ifactory_provider.h
*
* &prodname; has to deal with a relatively great number of elementary datas,
* reading them from different supports, storing and displaying them,
* then re-writing these same datas, with several output formats, and so on.
*
* This has rapidly become a pain, if not just a bug generator.
* Each new data must be described, have a schema to be stored in
* (historical storage subsystem) GConf; import and export assistants
* must be carefully updated to export the new data...
*
* The #NAIFactoryProvider aims to simplify and organize all the work
* which must be done around each and every elementary data. It is based
* on three main things:
*
* <orderedlist>
* <listitem>
* <formalpara>
* <title>Elementary datas are banalized.</title>
* <para>
* whether they are a string, an integer, a boolean, a simple
* or double-linked list, each elementary data is encapsuled
* into a #NADataBoxed, small sort of structure (incidentally,
* which acts almost as the new GLib #GVariant, but too late,
* guys :)).
* </para>
* </formalpara>
* </listitem>
* <listitem>
* <formalpara>
* <title>Our objects are de-structured.</title>
* <para>
* Instead of organizing our elementary datas into structures,
* our objects are just flat lists of #NADataBoxed.
* </para>
* </formalpara>
* </listitem>
* <listitem>
* <formalpara>
* <title>A full, centralized, data dictionary is defined.</title>
* <para>
* Now that our elementary datas are banalized and de-structured,
* it is simple enough to describe each of these datas with all
* iss properties in one single, centralized, place.
* </para>
* </formalpara>
* </listitem>
* </orderedlist>
*
* Of course, I/O providers are good candidates to be users of this
* #NAIFactoryProvider interface.
*
* Without this interface, each and every I/O provider must,
* for example when reading an item, have the list of data to be
* readen for each item, then read each individual data, then
* organize them in a I/O structure..
* Each time a new data is added to an object, as e.g. a new condition,
* then all available I/O providers must be updated: read the data,
* write the data, then display the data, and so on..
*
* With this #NAIFactoryProvider interface, the I/O provider has just to
* deal with reading/writing elementary types. It does need to know that
* it will have to read, name, tooltip, description. It just needs to know
* how to read a string.
* And while we do not introduce another data type, the I/O provider
* does not need any maintenance even if we add lot of new data, conditions
* labels, and so on.
*
* So, this is the interface used by data factory management system for
* providing serialization/unserialization services. This interface may
* be implemented by I/O providers which would take advantage of this
* system.
*
* <refsect2>
* <title>Versions historic</title>
* <table>
* <title>Historic of the versions of the #NAIFactoryProvider 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>#NAIFactoryProvider 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>
*/
#include "na-data-boxed.h"
#include "na-ifactory-object.h"
#include "na-ifactory-provider-provider.h"
......
......@@ -31,6 +31,41 @@
#ifndef __NAUTILUS_ACTIONS_API_NA_IIMPORTER_H__
#define __NAUTILUS_ACTIONS_API_NA_IIMPORTER_H__
/**
* SECTION: iimporter
* @title: NAIImporter
* @short_description: The Import Interface v 1
* @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>
*/
#include "na-object-item.h"
G_BEGIN_DECLS
......
......@@ -31,6 +31,68 @@
#ifndef __NAUTILUS_ACTIONS_API_NA_IIO_PROVIDER_H__
#define __NAUTILUS_ACTIONS_API_NA_IIO_PROVIDER_H__
/**
* SECTION: iio-provider
* @title: NAIIOProvider
* @short_description: The I/O Provider Interface v 1
* @include: nautilus-actions/na-iio-provider.h
*
* The #NAIIOProvider interface is defined in order to let internal
* and external plugins provide read and write accesses
* to an alternate storage subsystem.
*
* The #NAIIOProvider interface provides three types of services:
* <itemizedlist>
* <listitem>
* <para>
* load all items at startup;
* </para>
* </listitem>
* <listitem>
* <para>
* create, update or delete items via the management user interface;
* </para>
* </listitem>
* <listitem>
* <para>
* inform &prodname; when an item has been modified on the
* underlying storage subsystem.
* </para>
* </listitem>
* </itemizedlist>
*
* These services may be fully implemented by the I/O provider itself.
* Or, the I/O provider may also prefer to take advantage of the data
* factory management (see #NAIFactoryObject and #NAIFactoryProvider
* interfaces).
*
* <refsect2>
* <title>Versions historic</title>
* <table>
* <title>Historic of the versions of the #NAIIOProvider 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>#NAIIOProvider 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>
*/
#include "na-object-item.h"
G_BEGIN_DECLS
......
......@@ -33,102 +33,125 @@
/**
* SECTION: object
* @short_description: #NAObject class definition.
* @title: NAObject
* @short_description: The #NAObject Base Class Definition
* @include: nautilus-actions/na-object.h
*
* This is the base class of all our data object hierarchy.
* This is the base class of all our data object hierarchy. #NAObject is
* supposed to be used as a pure virtual base class, i.e. should only be
* derived.
*/
#include <glib-object.h>
G_BEGIN_DECLS
#define NA_OBJECT_TYPE ( na_object_object_get_type())
#define NA_OBJECT( object ) ( G_TYPE_CHECK_INSTANCE_CAST( object, NA_OBJECT_TYPE, NAObject ))
#define NA_OBJECT_CLASS( klass ) ( G_TYPE_CHECK_CLASS_CAST( klass, NA_OBJECT_TYPE, NAObjectClass ))
#define NA_IS_OBJECT( object ) ( G_TYPE_CHECK_INSTANCE_TYPE( object, NA_OBJECT_TYPE ))
#define NA_IS_OBJECT_CLASS( klass ) ( G_TYPE_CHECK_CLASS_TYPE(( klass ), NA_OBJECT_TYPE ))
#define NA_OBJECT_GET_CLASS( object ) ( G_TYPE_INSTANCE_GET_CLASS(( object ), NA_OBJECT_TYPE, NAObjectClass ))
#define NA_OBJECT_TYPE ( na_object_object_get_type())
#define NA_OBJECT( object ) ( G_TYPE_CHECK_INSTANCE_CAST( object, NA_OBJECT_TYPE, NAObject ))
#define NA_OBJECT_CLASS( klass ) ( G_TYPE_CHECK_CLASS_CAST( klass, NA_OBJECT_TYPE, NAObjectClass ))
#define NA_IS_OBJECT( object ) ( G_TYPE_CHECK_INSTANCE_TYPE( object, NA_OBJECT_TYPE ))
#define NA_IS_OBJECT_CLASS( klass ) ( G_TYPE_CHECK_CLASS_TYPE(( klass ), NA_OBJECT_TYPE ))
#define NA_OBJECT_GET_CLASS( object ) ( G_TYPE_INSTANCE_GET_CLASS(( object ), NA_OBJECT_TYPE, NAObjectClass ))
typedef struct NAObjectPrivate NAObjectPrivate;
typedef struct _NAObjectPrivate NAObjectPrivate;
typedef struct {
/*< private >*/
GObject parent;
NAObjectPrivate *private;
}
NAObject;
typedef struct NAObjectClassPrivate NAObjectClassPrivate;
typedef struct _NAObjectClassPrivate NAObjectClassPrivate;
/**
* NAObjectClass:
* @dump: Dumps the #NAObject -part of the #NAObject -derived object.
* @copy: Copies a #NAObject to another.
* @are_equal: Tests if two #NAObject are equal.
* @is_valid: Tests if a #NAObject is valid.
*
* The #NAObjectClass defines some methods available to derived classes.
*/
typedef struct {
/*< private >*/
GObjectClass parent;
NAObjectClassPrivate *private;
/*< public >*/
/**
* dump:
* @object: the #NAObject-derived object to be dumped.
* @object: the NAObject-derived object to be dumped.
*
* Dumps via g_debug the content of the object.
*
* #NAObject class takes care of calling this function for each
* NAObject class takes care of calling this function for each
* derived class, starting from topmost base class up to most-
* derived one. Each derived class has so only to take care of
* dumping its own data.
*
* Since: Nautilus-Actions v 2.30.
*/
void ( *dump ) ( const NAObject *object );
/**
* copy:
* @target: the #NAObject-derived object which will receive data.
* @source: the #NAObject-derived object which will provide data.
* @target: the NAObject-derived object which will receive data.
* @source: the NAObject-derived object which will provide data.
* @recursive: whether children should be recursively copied.
*
* Copies data and properties from @source to @target.
*
* Each derived class should take care of implementing this function
* when relevant. #NAObject class will take care of calling this
* when relevant. NAObject class will take care of calling this
* function for each class of the hierarchy, starting from topmost
* base class up to the most-derived one. Each class has so only to
* take care of dumping its own data.
*
* Since: Nautilus-Actions v 2.30.
*/
void ( *copy ) ( NAObject *target, const NAObject *source, gboolean recursive );
/**
* are_equal:
* @a: a first #NAObject object.
* @b: a second #NAObject object to be compared to the first one.
* @a: a first NAObject object.
* @b: a second NAObject object to be compared to the first one.
*
* Compares the two objects.
*
* Returns: %TRUE if @a and @b are identical, %FALSE else.
*
* Each derived class should take care of implementing this function
* when relevant. #NAObject class will take care of calling this
* when relevant. NAObject class will take care of calling this
* function for each class of the hierarchy, starting from topmost
* base class up to the most-derived one, at least while result
* stays at %TRUE.
* stays at TRUE.
* As soon as a difference is detected, the calling sequence will
* be stopped, and the result returned.
*
* Returns: TRUE if @a and @b are identical, FALSE else.
*
* Since: Nautilus-Actions v 2.30.
*/
gboolean ( *are_equal )( const NAObject *a, const NAObject *b );
/**
* is_valid:
* @object: the #NAObject object to be checked.
* @object: the NAObject object to be checked.
*
* Checks @object for validity.
*
* Returns: %TRUE if @object is valid, %FALSE else.
*
* A #NAObject is valid if its internal identifiant is set.
* A NAObject is valid if its internal identifiant is set.
*
* Each derived class should take care of implementing this function
* when relevant. #NAObject class will take care of calling this
* when relevant. NAObject class will take care of calling this
* function for each class of the hierarchy, starting from topmost
* base class up to the most-derived one, at least while result
* stays at %TRUE.
* stays at TRUE.
* As soon as a difference is detected, the calling sequence will
* be stopped, and the result returned.
*
* Returns: TRUE if @object is valid, FALSE else.
*
* Since: Nautilus-Actions v 2.30.
*/
gboolean ( *is_valid ) ( const NAObject *object );
}
......
......@@ -41,42 +41,6 @@
#include <api/na-data-types.h>
#include <api/na-data-boxed.h>
/**
* SECTION: data-boxed
* @title: NADataBoxed
* @short_description: The Data Factory Element 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 {
......
......@@ -36,17 +36,6 @@
#include <api/na-data-def.h>
/**
* SECTION: data-def
* @title: NADataDef, NADataGroup
* @short_description: The Data Factory Structure Definitions
* @include: nautilus-actions/na-data-def.h
*
* #NADataDef and #NADataGroup are structures which handle the list of
* elementary datas for each and every #NAObjectItem which happens to
* implement the #NAIFactoryObject interface.
*/
/**
* na_data_def_get_data_def:
* @group: a #NADataGroup structure array.
......
......@@ -34,13 +34,6 @@
#include <api/na-data-types.h>
/**
* SECTION: data-type
* @title: NADataType
* @short_description: The Data Factory Type Definitions
* @include: nautilus-actions/na-data-types.h
*/