From b77c7192f536108e07ffaf19a58e6bff9b011a93 Mon Sep 17 00:00:00 2001 From: Iain Holmes Date: Wed, 17 Jan 2001 18:27:02 +0000 Subject: Some API documentation for the importer svn path=/trunk/; revision=7589 --- doc/devel/ChangeLog | 11 ++ doc/devel/Makefile.am | 7 +- doc/devel/evolution-devel-guide.sgml | 5 + doc/devel/importer/.cvsignore | 3 + doc/devel/importer/Makefile.am | 127 +++++++++++++++++++++ .../importer/evolution-shell-importer-sections.txt | 58 ++++++++++ doc/devel/importer/evolution-shell-importer.args | 0 .../importer/evolution-shell-importer.heirarchy | 5 + .../importer/evolution-shell-importer.hierarchy | 8 ++ doc/devel/importer/evolution-shell-importer.types | 7 ++ doc/devel/importer/private-reference.sgml | 20 ++++ doc/devel/importer/public-reference.sgml | 20 ++++ .../importer/tmpl/evolution-importer-client.sgml | 96 ++++++++++++++++ doc/devel/importer/tmpl/evolution-importer.sgml | 98 ++++++++++++++++ .../tmpl/evolution-shell-importer-unused.sgml | 0 doc/devel/reference.sgml | 2 + help/devel/ChangeLog | 11 ++ help/devel/Makefile.am | 7 +- help/devel/evolution-devel-guide.sgml | 5 + help/devel/importer/.cvsignore | 3 + help/devel/importer/Makefile.am | 127 +++++++++++++++++++++ .../importer/evolution-shell-importer-sections.txt | 58 ++++++++++ help/devel/importer/evolution-shell-importer.args | 0 .../importer/evolution-shell-importer.heirarchy | 5 + .../importer/evolution-shell-importer.hierarchy | 8 ++ help/devel/importer/evolution-shell-importer.types | 7 ++ help/devel/importer/private-reference.sgml | 20 ++++ help/devel/importer/public-reference.sgml | 20 ++++ .../importer/tmpl/evolution-importer-client.sgml | 96 ++++++++++++++++ help/devel/importer/tmpl/evolution-importer.sgml | 98 ++++++++++++++++ .../tmpl/evolution-shell-importer-unused.sgml | 0 help/devel/reference.sgml | 2 + 32 files changed, 930 insertions(+), 4 deletions(-) create mode 100644 doc/devel/importer/.cvsignore create mode 100644 doc/devel/importer/Makefile.am create mode 100644 doc/devel/importer/evolution-shell-importer-sections.txt create mode 100644 doc/devel/importer/evolution-shell-importer.args create mode 100644 doc/devel/importer/evolution-shell-importer.heirarchy create mode 100644 doc/devel/importer/evolution-shell-importer.hierarchy create mode 100644 doc/devel/importer/evolution-shell-importer.types create mode 100644 doc/devel/importer/private-reference.sgml create mode 100644 doc/devel/importer/public-reference.sgml create mode 100644 doc/devel/importer/tmpl/evolution-importer-client.sgml create mode 100644 doc/devel/importer/tmpl/evolution-importer.sgml create mode 100644 doc/devel/importer/tmpl/evolution-shell-importer-unused.sgml create mode 100644 help/devel/importer/.cvsignore create mode 100644 help/devel/importer/Makefile.am create mode 100644 help/devel/importer/evolution-shell-importer-sections.txt create mode 100644 help/devel/importer/evolution-shell-importer.args create mode 100644 help/devel/importer/evolution-shell-importer.heirarchy create mode 100644 help/devel/importer/evolution-shell-importer.hierarchy create mode 100644 help/devel/importer/evolution-shell-importer.types create mode 100644 help/devel/importer/private-reference.sgml create mode 100644 help/devel/importer/public-reference.sgml create mode 100644 help/devel/importer/tmpl/evolution-importer-client.sgml create mode 100644 help/devel/importer/tmpl/evolution-importer.sgml create mode 100644 help/devel/importer/tmpl/evolution-shell-importer-unused.sgml 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 + + * 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 * 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 @@ + + + + + Evolution"> Wombat"> Camel"> 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 @@ +evolution-importer.h +evolution-importer-client.h + +
+evolution-importer +EVOLUTION_IMPORTER +EvolutionImporter + +EvolutionImporterSupportFormatFn +EvolutionImporterLoadFileFn +EvolutionImporterProcessItemFn +EvolutionImporterGetErrorFn + +EvolutionImporterResult + +evolution_importer_new + + +EVOLUTION_TYPE_IMPORTER +EVOLUTION_IMPORTER +EVOLUTION_IS_IMPORTER +EVOLUTION_IMPORTER_CLASS +EVOLUTION_IS_IMPORTER_CLASS +evolution_importer_get_type + + +EvolutionImporter +EvolutionImporterPrivate + +
+ +
+evolution-importer-client +EVOLUTION_IMPORTER_CLIENT +EvolutionImporterClient + +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 + + +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 + + +EvolutionImporterClient +EvolutionImporterClientPrivate + +
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 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 +#include +#include +#include + +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 @@ + + Importer Private API Reference + + + + This part presents the class and function reference for the + private APIs of the different components of the &Evolution; + Import Framework. + + + + &EvolutionImporterClient; + + + 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 @@ + + Importer Public API Reference + + + + This part presents the class and function reference for the + public APIs of the different components of the &Evolution; + Import Framework. + + + + &EvolutionImporter; + + + 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 @@ + +EvolutionImporterClient + + +GTK+ object for communication with importer components. + + + + 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. + + + + + + + + + + Casts a #GtkObject into an #EvolutionImporterClient + + +@obj: A GtkObject. + + + + + The type of the function that will be called when the importer has something + to report to the shell. + + +@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(). + + + + + + + +@objref: +@Returns: + + + + + + + +@id: +@Returns: + + + + + + + +@client: +@filename: +@Returns: + + + + + + + +@client: +@filename: +@Returns: + + + + + + + +@client: +@callback: +@closure: + + + + + + + +@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 @@ + +EvolutionImporter + + +GTK+ object used to create Evolution Importers . + + + + The #EvolutionImporter object provides a GTK+ wrapper for the CORBA + interface that is used to communicate between the importer and the + Evolution shell. + + + + + + + + + + Casts a #GtkObject to an #EvolutionImporter + + +@obj: A GTK+ object. + + + + + The function that is called when the Evolution shell wants to know + whether this #EvolutionImporter is able to support the file specified + by @filename. + + +@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 + + + + + The function that is called when the Evolution shell wants the + #EvolutionImporter to load a file. + + +@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. + + + + + The function that is called when the Evolution shell wants the + #EvolutionImporter to process the next item in the file. + + + + This function may process one item, or it may process as many as it + wants/is able to. + + +@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. + + + + + The function that is called when the Evolution shell wants to find out + about any errors that may have occurred. + + +@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. + + + + + These values describe the result of the processItem CORBA method. + + + + + + + + +@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 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 @@ &calendar-public-reference; + &importer-public-reference; + &importer-private-reference; diff --git a/help/devel/importer/public-reference.sgml b/help/devel/importer/public-reference.sgml new file mode 100644 index 0000000000..ba99c9b309 --- /dev/null +++ b/help/devel/importer/public-reference.sgml @@ -0,0 +1,20 @@ + + Importer Public API Reference + + + + This part presents the class and function reference for the + public APIs of the different components of the &Evolution; + Import Framework. + + + + &EvolutionImporter; + + + diff --git a/help/devel/importer/tmpl/evolution-importer-client.sgml b/help/devel/importer/tmpl/evolution-importer-client.sgml new file mode 100644 index 0000000000..8e911a91dd --- /dev/null +++ b/help/devel/importer/tmpl/evolution-importer-client.sgml @@ -0,0 +1,96 @@ + +EvolutionImporterClient + + +GTK+ object for communication with importer components. + + + + 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. + + + + + + + + + + Casts a #GtkObject into an #EvolutionImporterClient + + +@obj: A GtkObject. + + + + + The type of the function that will be called when the importer has something + to report to the shell. + + +@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(). + + + + + + + +@objref: +@Returns: + + + + + + + +@id: +@Returns: + + + + + + + +@client: +@filename: +@Returns: + + + + + + + +@client: +@filename: +@Returns: + + + + + + + +@client: +@callback: +@closure: + + + + + + + +@client: +@Returns: + + diff --git a/help/devel/importer/tmpl/evolution-importer.sgml b/help/devel/importer/tmpl/evolution-importer.sgml new file mode 100644 index 0000000000..06aa2ea762 --- /dev/null +++ b/help/devel/importer/tmpl/evolution-importer.sgml @@ -0,0 +1,98 @@ + +EvolutionImporter + + +GTK+ object used to create Evolution Importers . + + + + The #EvolutionImporter object provides a GTK+ wrapper for the CORBA + interface that is used to communicate between the importer and the + Evolution shell. + + + + + + + + + + Casts a #GtkObject to an #EvolutionImporter + + +@obj: A GTK+ object. + + + + + The function that is called when the Evolution shell wants to know + whether this #EvolutionImporter is able to support the file specified + by @filename. + + +@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 + + + + + The function that is called when the Evolution shell wants the + #EvolutionImporter to load a file. + + +@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. + + + + + The function that is called when the Evolution shell wants the + #EvolutionImporter to process the next item in the file. + + + + This function may process one item, or it may process as many as it + wants/is able to. + + +@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. + + + + + The function that is called when the Evolution shell wants to find out + about any errors that may have occurred. + + +@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. + + + + + These values describe the result of the processItem CORBA method. + + + + + + + + +@support_format_fn: +@load_file_fn: +@process_item_fn: +@get_error_fn: +@closure: +@Returns: + + diff --git a/help/devel/importer/tmpl/evolution-shell-importer-unused.sgml b/help/devel/importer/tmpl/evolution-shell-importer-unused.sgml new file mode 100644 index 0000000000..e69de29bb2 diff --git a/help/devel/reference.sgml b/help/devel/reference.sgml index 3773821a0f..ae675a7722 100644 --- a/help/devel/reference.sgml +++ b/help/devel/reference.sgml @@ -35,6 +35,8 @@ &calendar-public-reference; + &importer-public-reference; + &importer-private-reference;