Add some comments to document the interface.

svn path=/trunk/; revision=16922

1 files changed, 45 insertions, 13 deletions

diff --git a/shell/Evolution-ShellComponent.idl b/shell/Evolution-ShellComponent.idl
index ad8b7af118..495553e8f7 100644
--- a/shell/Evolution-ShellComponent.idl
+++ b/shell/Evolution-ShellComponent.idl
@@ -5,7 +5,7 @@
  * Authors:
  *   Ettore Perazzoli <ettore@ximian.com>
  *
- * Copyright (C) 2000, 2001 Ximian, Inc.
+ * Copyright (C) 2000, 2001, 2002 Ximian, Inc.
  */
 
 #include <Bonobo.h>
@@ -14,6 +14,7 @@ module GNOME {
 module Evolution {
 	interface Shell;
 
+	/* Definition for a folder type.  */
 	struct FolderType {
 		string name;
 		string iconName;
@@ -28,9 +29,12 @@ module Evolution {
 	};
 	typedef sequence<FolderType> FolderTypeList;
 
+	/* URI schemas, e.g. mailto:.  */
 	typedef string URISchema;
 	typedef sequence<URISchema> URISchemaList;
 
+	/* A type of item that the component can create when asked by the user,
+	   e.g. a mail message or an appointment.  */
 	struct UserCreatableItemType {
 		string id;
 		string description;
@@ -43,51 +47,69 @@ module Evolution {
 	interface ShellComponentListener;
 
 	interface ShellComponent : Bonobo::Unknown {
+		exception AlreadyOwned {};
+		exception Busy {};
+		exception InternalError {};
+		exception NotFound {};
+		exception NotOwned {};
+		exception OldOwnerHasDied {};
+		exception UnsupportedSchema {};
+		exception UnsupportedType {};
+
+		/* List of folders that the component supports.  */
 		readonly attribute FolderTypeList supportedTypes;
+
+		/* Custom URI schemas that the component supports.
+		   (e.g. mailto, see ::handleExternalURI).  */
 		readonly attribute URISchemaList externalUriSchemas ;
-		readonly attribute UserCreatableItemTypeList userCreatableItemTypes;
 
-		exception AlreadyOwned {};
-		exception OldOwnerHasDied {};
+		/* List of the item that the user can create (see
+		   ::userCreateNewItem).  */
+		readonly attribute UserCreatableItemTypeList userCreatableItemTypes;
 
+		/* This method is invoked after the components is activated by
+		   the shell to notify the component that the shell is
+		   alive.  */
 		void setOwner (in Shell shell, in string evolution_homedir)
 			raises (AlreadyOwned, OldOwnerHasDied);
 
-		exception NotOwned {};
-
+		/* This is invoked when the shell releases the component.  */
 		void unsetOwner ()
 			raises (NotOwned);
 
+		/* Notify the component of whether the shell is currently
+		 * running in interactive mode or not.  (I.e. basically,
+		 * whether there are any Evolution windows on the screen.)  */
 		void interactive (in boolean now_interactive);
 
+		/* Send debugging output to the file specified.  */
 		void debug (in string log_path);
 
-		/* FIXME: We might want more exceptions here.  */
-		exception NotFound {};
-		exception UnsupportedType {};
-		exception UnsupportedSchema {};
-		exception InternalError {};
-
+		/* Create a view for the specified @physical URI.  */
 		Bonobo::Control createView (in string physical_uri,
 					    in string type,
 					    in string view_info)
 			raises (NotFound, UnsupportedType, InternalError);
 
+		/* Handle a registered external URI scheme (eg. mailto:).  */
 		void handleExternalURI (in string external_uri)
 			raises (NotFound, UnsupportedSchema, InternalError);
 
-		exception Busy {};
+		/* Folder operations:  */
 
+		/* 1. Create a folder.  */
 		void createFolderAsync (in ShellComponentListener listener,
 					in string physical_uri,
 					in string type)
 			raises (Busy);
 
+		/* 2. Remove a folder.  */
 		void removeFolderAsync (in ShellComponentListener listener,
 					in string physical_uri,
 					in string type)
 			raises (Busy);
 
+		/* 3. Copy/move a folder.  */
 		void xferFolderAsync (in ShellComponentListener listener,
 				      in string source_physical_uri,
 				      in string destination_physical_uri,
@@ -95,15 +117,25 @@ module Evolution {
 				      in boolean remove_source)
 			raises (Busy);
 
+		/* Ask the component to populate the UIC with the
+		   folder-specific menu items of the folder at the specified
+		   @physical_uri.  */
 		void populateFolderContextMenu (in Bonobo::UIContainer uih,
 						in string physical_uri,
 						in string type);
 
+		/* Make the component create a new item of the specify @id in
+		   the folder specified by @parent_folder_physical_uri.  This
+		   is supposed to pop up a dialog (say, the Addressbook
+		   editor) when necessary.  */
 		void userCreateNewItem (in string id,
 					in string parent_folder_physical_uri,
 					in string parent_folder_type)
 			raises (UnsupportedType);
 
+		/* Make the component start a Send/Receive operation.  If
+		   @show_dialog is true, display a progress dialog for the
+		   operation as well.  */
 		void sendReceive (in boolean show_dialog);
 	};