Some API documentation for the importer

svn path=/trunk/; revision=7589

16 files changed, 465 insertions, 2 deletions

diff --git a/doc/devel/ChangeLog b/doc/devel/ChangeLog
index 3c06aedc0b..6fc944b3c7 100644
--- a/doc/devel/ChangeLog
+++ b/doc/devel/ChangeLog
@@ -1,3 +1,14 @@
+2001-01-17  Iain Holmes  <iain@ximian.com>
+
+	* Makefile.am (local_entities): Added the importer stuff.
+
+	* evolution-devel-guide.sgml: Added entities for the importer documents.
+
+	* reference.sgml: Added the public and private APIs for the importer.
+
+	* importer/*: New directory containing all the documenation for the
+	importer.
+
 2001-01-17  Federico Mena Quintero  <federico@ximian.com>
 
 	* evolution-devel-guide.sgml: Ximianified.
diff --git a/doc/devel/Makefile.am b/doc/devel/Makefile.am
index 77f9354ba9..b69b34d5d8 100644
--- a/doc/devel/Makefile.am
+++ b/doc/devel/Makefile.am
@@ -1,4 +1,4 @@
-SUBDIRS = calendar
+SUBDIRS = calendar importer
 
 # The name of the module.
 DOC_MODULE=evolution-devel-guide
@@ -32,7 +32,10 @@ local_entities =					\
 	calendar/cal-util/sgml/cal-component.sgml	\
 	calendar/cal-util/sgml/cal-recur.sgml		\
 	calendar/cal-util/sgml/cal-util.sgml		\
-	calendar/cal-util/sgml/timeutil.sgml
+	calendar/cal-util/sgml/timeutil.sgml		\
+							\
+	importer/sgml/evolution-importer.sgml		\
+	importer/sgml/evolution-importer-client.sgml
 
 EXTRA_DIST =			\
 	$(content_files)
diff --git a/doc/devel/evolution-devel-guide.sgml b/doc/devel/evolution-devel-guide.sgml
index a932839120..29401c239c 100644
--- a/doc/devel/evolution-devel-guide.sgml
+++ b/doc/devel/evolution-devel-guide.sgml
@@ -13,6 +13,11 @@
 <!ENTITY cal-util SYSTEM "calendar/cal-util/sgml/cal-util.sgml">
 <!ENTITY timeutil SYSTEM "calendar/cal-util/sgml/timeutil.sgml">
 
+<!ENTITY importer-public-reference SYSTEM "importer/public-reference.sgml">
+<!ENTITY importer-private-reference SYSTEM "importer/private-reference.sgml">
+<!ENTITY EvolutionImporter SYSTEM "importer/sgml/evolution-importer.sgml">
+<!ENTITY EvolutionImporterClient SYSTEM "importer/sgml/evolution-importer-client.sgml">
+
 <!ENTITY Evolution "<application>Evolution</application>">
 <!ENTITY Wombat "<application>Wombat</application>">
 <!ENTITY Camel "<application>Camel</application>">
diff --git a/doc/devel/importer/.cvsignore b/doc/devel/importer/.cvsignore
new file mode 100644
index 0000000000..0842a93f7a
--- /dev/null
+++ b/doc/devel/importer/.cvsignore
@@ -0,0 +1,3 @@
+sgml
+Makefile
+Makefile.in
diff --git a/doc/devel/importer/Makefile.am b/doc/devel/importer/Makefile.am
new file mode 100644
index 0000000000..9f1c046085
--- /dev/null
+++ b/doc/devel/importer/Makefile.am
@@ -0,0 +1,127 @@
+# The name of the module.
+DOC_MODULE=evolution-shell-importer
+
+# The directory containing the source code
+DOC_SOURCE_DIR=$(EVOLUTION_DIR)/shell/importer
+
+CFLAGS ="						\
+	-I$(top_srcdir)/shell/importer			\
+	-I$(top_srcdir)/shell				\
+	-I$(top_srcdir)					\
+	-I$(top_builddir)				\
+	$(BONOBO_VFS_GNOME_CFLAGS)			\
+	"
+
+LDFLAGS="								\
+	$(BONOBO_VFS_GNOME_LIBS)					\
+	$(top_builddir)/shell/importer/.libs/libevolution-importer.a	\
+	"
+
+DOC_DIR=$(datadir)/gnome/html
+
+DOC_DIR_INSTALL_FILES =					\
+	evolution-shell-importer.args			\
+	evolution-shell-importer.hierarchy		\
+	evolution-shell-importer.signals		\
+	evolution-shell-importer.types			\
+	evolution-shell-importer-decl.txt		\
+	evolution-shell-importer-sections.txt
+
+SOURCE_FILES =							\
+	$(top_srcdir)/shell/importer/evolution-importer.c	\
+	$(top_srcdir)/shell/importer/evolution-importer.h	\
+	$(top_srcdir)/shell/importer/evolution-importer-client.c	\
+	$(top_srcdir)/shell/importer/evolution-importer-client.h
+
+IGNORED_HEADER_FILES =		\
+	GNOME_Evolution_Importer.h	\
+	importer.h
+	
+scan_generated =						\
+	evolution-shell-importer-decl.txt			\
+	evolution-shell-importer.args				\
+	evolution-shell-importer.hierarchy			\
+	evolution-shell-importer.signals			\
+	evolution-shell-importer.types
+
+tmpl_dependencies =						\
+	evolution-shell-importer-decl.txt			\
+	evolution-shell-importer-sections.txt			\
+	evolution-shell-importer.args				\
+	evolution-shell-importer.hierarchy			\
+	evolution-shell-importer.signals
+
+tmpl_sources = 						\
+	tmpl/importer.sgml		\
+	tmpl/evolution-shell-importer-unused.sgml
+
+tmpl_generated =					\
+	evolution-shell-importer-unused.txt
+
+sgml_dependencies =					\
+	evolution-shell-importer-decl.txt		\
+	evolution-shell-importer-sections.txt		\
+	evolution-shell-importer.args			\
+	evolution-shell-importer.hierarchy		\
+	evolution-shell-importer.signals		\
+	tmpl/importer.sgml
+
+sgml_generated =						\
+	sgml/importer.sgml					\
+	sgml/evolution-shell-importer-doc.bottom		\
+	sgml/evolution-shell-importer-doc.top			\
+	sgml/object_index.sgml					\
+	sgml/tree_index.sgml
+
+EXTRA_DIST =							\
+	evolution-shell-importer.args				\
+	evolution-shell-importer.hierarchy			\
+	evolution-shell-importer.signals			\
+	evolution-shell-importer.types				\
+	evolution-shell-importer-decl.txt			\
+	evolution-shell-importer-sections.txt
+
+all: $(sgml_generated)
+
+if ENABLE_GTK_DOC
+scan $(scan_generated): $(SOURCE_FILES)
+	-(cd $(srcdir)						\
+	  && env CFLAGS=$(CFLAGS) LDFLAGS=$(LDFLAGS)		\
+		 gtkdoc-scanobj --module=$(DOC_MODULE)		\
+	  && gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR)		\
+			 --ignore-headers="$(IGNORED_HEADER_FILES)" )
+
+templates $(tmpl_sources) $(tmpl_generated): $(tmpl_dependencies)
+	cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE)
+
+sgml $(sgml_generated): $(sgml_dependencies)
+	cd $(srcdir) \
+	&& gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR)
+else
+scan $(scan_generated): $(SOURCE_FILE)
+
+templates $(tmpl_sources) $(tmpl_generated): $(tmpl_dependencies)
+
+sgml $(sgml_generated): $(sgml_dependencies)
+endif
+
+clean-local:
+	rm -f *~ *.bak *.signals *-unused.txt
+
+maintainer-clean-local: clean
+	cd $(srcdir) && rm -rf sgml $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
+
+install-data-local:
+	$(mkinstalldirs) $(DOC_DIR)
+	for i in $(DOC_DIR_INSTALL_FILES); do		\
+		$(INSTALL_DATA) $$i $(DOC_DIR);		\
+	done
+
+dist-hook:
+	mkdir $(distdir)/sgml
+	mkdir $(distdir)/tmpl
+	-cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl
+	-cp $(srcdir)/sgml/*.sgml $(distdir)/sgml
+	-cp $(srcdir)/sgml/*.bottom $(srcdir)/sgml/*.top $(distdir)/sgml
+
+.PHONY: scan templates sgml
diff --git a/doc/devel/importer/evolution-shell-importer-sections.txt b/doc/devel/importer/evolution-shell-importer-sections.txt
new file mode 100644
index 0000000000..f14b8addcb
--- /dev/null
+++ b/doc/devel/importer/evolution-shell-importer-sections.txt
@@ -0,0 +1,58 @@
+<INCLUDE>evolution-importer.h</INCLUDE>
+<INCLUDE>evolution-importer-client.h</INCLUDE>
+
+<SECTION>
+<FILE>evolution-importer</FILE>
+EVOLUTION_IMPORTER
+<TITLE>EvolutionImporter</TITLE>
+
+EvolutionImporterSupportFormatFn
+EvolutionImporterLoadFileFn
+EvolutionImporterProcessItemFn
+EvolutionImporterGetErrorFn
+
+EvolutionImporterResult
+
+evolution_importer_new
+
+<SUBSECTION Standard>
+EVOLUTION_TYPE_IMPORTER
+EVOLUTION_IMPORTER
+EVOLUTION_IS_IMPORTER
+EVOLUTION_IMPORTER_CLASS
+EVOLUTION_IS_IMPORTER_CLASS
+evolution_importer_get_type
+
+<SUBSECTION Private>
+EvolutionImporter
+EvolutionImporterPrivate
+
+</SECTION>
+
+<SECTION>
+<FILE>evolution-importer-client</FILE>
+EVOLUTION_IMPORTER_CLIENT
+<TITLE>EvolutionImporterClient</TITLE>
+
+EvolutionImporterClientCallback
+
+evolution_importer_client_new
+evolution_importer_client_new_from_id
+evolution_importer_client_support_format
+evolution_importer_client_load_file
+evolution_importer_client_process_item
+evolution_importer_client_get_error
+
+<SUBSECTION Standard>
+EVOLUTION_TYPE_IMPORTER_CLIENT
+EVOLUTION_IMPORTER_CLIENT
+EVOLUTION_IMPORTER_CLIENT_CLASS
+EVOLUTION_IS_IMPORTER_CLIENT
+EVOLUTION_IS_IMPORTER_CLIENT_CLASS
+evolution_importer_client_get_type
+
+<SUBSECTION Private>
+EvolutionImporterClient
+EvolutionImporterClientPrivate
+
+</SECTION>
diff --git a/doc/devel/importer/evolution-shell-importer.args b/doc/devel/importer/evolution-shell-importer.args
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/doc/devel/importer/evolution-shell-importer.args
diff --git a/doc/devel/importer/evolution-shell-importer.heirarchy b/doc/devel/importer/evolution-shell-importer.heirarchy
new file mode 100644
index 0000000000..78e430d311
--- /dev/null
+++ b/doc/devel/importer/evolution-shell-importer.heirarchy
@@ -0,0 +1,5 @@
+GtkObject
+  BonoboObject
+    EvolutionImporter
+  BonoboObjectClient
+    EvolutionImporterClient
diff --git a/doc/devel/importer/evolution-shell-importer.hierarchy b/doc/devel/importer/evolution-shell-importer.hierarchy
new file mode 100644
index 0000000000..239d0026e0
--- /dev/null
+++ b/doc/devel/importer/evolution-shell-importer.hierarchy
@@ -0,0 +1,8 @@
+GtkObject
+  GtkWidget
+    GtkRange
+    GtkContainer
+  BonoboObject
+    EvolutionImporter
+    Handle to remote Bonobo::Unknown
+      EvolutionImporterClient
diff --git a/doc/devel/importer/evolution-shell-importer.types b/doc/devel/importer/evolution-shell-importer.types
new file mode 100644
index 0000000000..60143b3eb3
--- /dev/null
+++ b/doc/devel/importer/evolution-shell-importer.types
@@ -0,0 +1,7 @@
+#include <gnome.h>
+#include <bonobo.h>
+#include <evolution/importer/evolution-importer.h>
+#include <evolution/importer/evolution-importer-client.h>
+
+evolution_importer_get_type
+evolution_importer_client_get_type
diff --git a/doc/devel/importer/private-reference.sgml b/doc/devel/importer/private-reference.sgml
new file mode 100644
index 0000000000..28f7d681c7
--- /dev/null
+++ b/doc/devel/importer/private-reference.sgml
@@ -0,0 +1,20 @@
+  <reference id="importer-private-reference">
+    <title>Importer Private API Reference</title>
+
+    <partintro>
+      <para>
+	This part presents the class and function reference for the
+	private APIs of the different components of the &Evolution;
+	Import Framework.
+      </para>
+    </partintro>
+
+    &EvolutionImporterClient;
+  </reference>
+
+<!--
+Local variables:
+mode: sgml
+sml-parent-document: ("../evolution-devel-guide.sgml" "book" "part" "")
+End:
+-->
diff --git a/doc/devel/importer/public-reference.sgml b/doc/devel/importer/public-reference.sgml
new file mode 100644
index 0000000000..ba99c9b309
--- /dev/null
+++ b/doc/devel/importer/public-reference.sgml
@@ -0,0 +1,20 @@
+  <reference id="importer-public-reference">
+    <title>Importer Public API Reference</title>
+
+    <partintro>
+      <para>
+	This part presents the class and function reference for the
+	public APIs of the different components of the &Evolution;
+	Import Framework.
+      </para>
+    </partintro>
+
+    &EvolutionImporter;
+  </reference>
+
+<!--
+Local variables:
+mode: sgml
+sml-parent-document: ("../evolution-devel-guide.sgml" "book" "part" "")
+End:
+-->
diff --git a/doc/devel/importer/tmpl/evolution-importer-client.sgml b/doc/devel/importer/tmpl/evolution-importer-client.sgml
new file mode 100644
index 0000000000..8e911a91dd
--- /dev/null
+++ b/doc/devel/importer/tmpl/evolution-importer-client.sgml
@@ -0,0 +1,96 @@
+<!-- ##### SECTION Title ##### -->
+EvolutionImporterClient
+
+<!-- ##### SECTION Short_Description ##### -->
+GTK+ object for communication with importer components.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+  The #EvolutionImporterClient provides a GTK+ wrapper for the CORBA
+  interfaces that are used to communicate between the shell and the
+  importers. The #EvolutionImporterClient removes the need for CORBA
+  calls in the shell.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### MACRO EVOLUTION_IMPORTER_CLIENT ##### -->
+<para>
+  Casts a #GtkObject into an #EvolutionImporterClient
+</para>
+
+@obj: A GtkObject.
+
+
+<!-- ##### USER_FUNCTION EvolutionImporterClientCallback ##### -->
+<para>
+  The type of the function that will be called when the importer has something
+  to report to the shell.
+</para>
+
+@client: An #EvolutionImporterClient object.
+@result: An #EvolutionImporterResult describing the result of the action.
+@more_items: A #gboolean indicating whether there are any more items to be processed.
+@data: The data that was passed into evolution_importer_client_process_item().
+
+
+<!-- ##### FUNCTION evolution_importer_client_new ##### -->
+<para>
+
+</para>
+
+@objref: 
+@Returns: 
+
+
+<!-- ##### FUNCTION evolution_importer_client_new_from_id ##### -->
+<para>
+
+</para>
+
+@id: 
+@Returns: 
+
+
+<!-- ##### FUNCTION evolution_importer_client_support_format ##### -->
+<para>
+
+</para>
+
+@client: 
+@filename: 
+@Returns: 
+
+
+<!-- ##### FUNCTION evolution_importer_client_load_file ##### -->
+<para>
+
+</para>
+
+@client: 
+@filename: 
+@Returns: 
+
+
+<!-- ##### FUNCTION evolution_importer_client_process_item ##### -->
+<para>
+
+</para>
+
+@client: 
+@callback: 
+@closure: 
+
+
+<!-- ##### FUNCTION evolution_importer_client_get_error ##### -->
+<para>
+
+</para>
+
+@client: 
+@Returns: 
+
+
diff --git a/doc/devel/importer/tmpl/evolution-importer.sgml b/doc/devel/importer/tmpl/evolution-importer.sgml
new file mode 100644
index 0000000000..06aa2ea762
--- /dev/null
+++ b/doc/devel/importer/tmpl/evolution-importer.sgml
@@ -0,0 +1,98 @@
+<!-- ##### SECTION Title ##### -->
+EvolutionImporter
+
+<!-- ##### SECTION Short_Description ##### -->
+GTK+ object used to create Evolution Importers .
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+  The #EvolutionImporter object provides a GTK+ wrapper for the CORBA
+  interface that is used to communicate between the importer and the
+  Evolution shell.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### MACRO EVOLUTION_IMPORTER ##### -->
+<para>
+  Casts a #GtkObject to an #EvolutionImporter
+</para>
+
+@obj: A GTK+ object.
+
+
+<!-- ##### USER_FUNCTION EvolutionImporterSupportFormatFn ##### -->
+<para>
+  The function that is called when the Evolution shell wants to know
+  whether this #EvolutionImporter is able to support the file specified
+  by @filename. 
+</para>
+
+@importer: An #EvolutionImporter object.
+@filename: The name of file to check.
+@closure: The data that was passed into evolution_importer_new ().
+@Returns: #TRUE if the importer can handle the file, #FALSE otherwise
+
+
+<!-- ##### USER_FUNCTION EvolutionImporterLoadFileFn ##### -->
+<para>
+  The function that is called when the Evolution shell wants the 
+  #EvolutionImporter to load a file.
+</para>
+
+@importer: An #EvolutionImporter object.
+@filename: The name of the file to load.
+@closure: The data that was passed into evolution_importer_new ().
+@Returns: #TRUE on success, #FALSE otherwise.
+
+
+<!-- ##### USER_FUNCTION EvolutionImporterProcessItemFn ##### -->
+<para>
+  The function that is called when the Evolution shell wants the
+  #EvolutionImporter to process the next item in the file.
+</para>
+
+<para>
+  This function may process one item, or it may process as many as it
+  wants/is able to.
+</para>
+
+@importer: An #EvolutionImporter object.
+@listener: A #CORBA_Object that will be informed of the results.
+@closure: The data that was passed into evolution_importer_new ().
+@ev: A #CORBA_Environment for returning any CORBA exceptions that may occur.
+
+
+<!-- ##### USER_FUNCTION EvolutionImporterGetErrorFn ##### -->
+<para>
+  The function that is called when the Evolution shell wants to find out
+  about any errors that may have occurred.
+</para>
+
+@importer: An #EvolutionImporter object.
+@closure: The data that was passed into evolution_importer_new ().
+@Returns: A string with the error message, or #NULL if there was none.
+
+
+<!-- ##### ENUM EvolutionImporterResult ##### -->
+<para>
+  These values describe the result of the processItem CORBA method.
+</para>
+
+
+<!-- ##### FUNCTION evolution_importer_new ##### -->
+<para>
+
+</para>
+
+@support_format_fn: 
+@load_file_fn: 
+@process_item_fn: 
+@get_error_fn: 
+@closure: 
+@Returns: 
+
+
diff --git a/doc/devel/importer/tmpl/evolution-shell-importer-unused.sgml b/doc/devel/importer/tmpl/evolution-shell-importer-unused.sgml
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/doc/devel/importer/tmpl/evolution-shell-importer-unused.sgml
diff --git a/doc/devel/reference.sgml b/doc/devel/reference.sgml
index 3773821a0f..ae675a7722 100644
--- a/doc/devel/reference.sgml
+++ b/doc/devel/reference.sgml
@@ -35,6 +35,8 @@
     </partintro>
 
     &calendar-public-reference;
+    &importer-public-reference;
+    &importer-private-reference;
   </part>
 
 <!--