Docs docs docs - Federico

svn path=/trunk/; revision=4206

1 files changed, 106 insertions, 42 deletions

diff --git a/doc/devel/calendar/cal-client/tmpl/cal-client.sgml b/doc/devel/calendar/cal-client/tmpl/cal-client.sgml
index 7fdc69bfdc..d2205b5b22 100644
--- a/doc/devel/calendar/cal-client/tmpl/cal-client.sgml
+++ b/doc/devel/calendar/cal-client/tmpl/cal-client.sgml
@@ -2,46 +2,90 @@
 CalClient
 
 <!-- ##### SECTION Short_Description ##### -->
-
+GTK+ object for communication with personal calendar server.
 
 <!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
-
+  <para>
+    The #CalClient object provides a nice GTK+ wrapper for the CORBA
+    interfaces that are used to communicate between calendar clients
+    and the personal calendar server in the user's Wombat daemon.
+  </para>
+
+  <para>
+    After a #CalClient object is created with cal_client_new(), it
+    should be asked to send a request to the personal calendar server
+    to load or create a calendar based on its URI.  The server will
+    asynchronously notify the client about completion of the request,
+    and will return an appropriate result code; this should be noted
+    by the client with the <link
+    linkend="CalClient--cal-loaded">cal_loaded</link> signal.
+  </para>
+
+  <para>
+    When a client asks the server to update or delete a calendar
+    component from the storage, the server will do so and then notify
+    all the clients about the update or removal.  This is the core of
+    the model/view split between calendar clients and the storage in
+    the personal calendar server.  Clients should watch the <link
+    linkend="calclient-obj-updated">obj_updated</link> and <link
+    linkend="calclient-obj-removed">obj_removed</link> signals on the
+    CalClient objects they create so that they can be notified about
+    changes in the storage.
+  </para>
 
 <!-- ##### SECTION See_Also ##### -->
-<para>
+  <para>
 
-</para>
+  </para>
 
 
 <!-- ##### MACRO CAL_CLIENT ##### -->
-<para>
+  <para>
+    Casts a #GtkObject to a #CalClient.
+  </para>
 
-</para>
-
-@obj: 
+@obj: A GTK+ object.
 
 
 <!-- ##### ENUM CalClientLoadStatus ##### -->
-<para>
-
-</para>
-
-@CAL_CLIENT_LOAD_SUCCESS: 
-@CAL_CLIENT_LOAD_ERROR: 
-@CAL_CLIENT_LOAD_IN_USE: 
-@CAL_CLIENT_LOAD_METHOD_NOT_SUPPORTED: 
+  <para>
+    These values describe the status of a calendar load or create
+    request.  After asking a calendar factory to load or create a
+    calendar, the provided listener will get notification about the
+    result in asynchronous fashion.  Such notification is represented
+    by one of these enumeration values.  For values other than
+    #CAL_CLIENT_LOAD_SUCCESS, the #CalClient object will not accept
+    any other operations on the calendar and it should just be
+    destroyed.
+  </para>
+
+@CAL_CLIENT_LOAD_SUCCESS: Indicates a successful load or create
+  operation; the corresponding calendar is ready for use.
+
+@CAL_CLIENT_LOAD_ERROR: Indicates an error while loading or creating
+  the calendar.
+
+@CAL_CLIENT_LOAD_IN_USE: Indicates that a create request failed
+  because the specified calendar was already being used by another
+  client.
+
+@CAL_CLIENT_LOAD_METHOD_NOT_SUPPORTED: Indicates an error due to
+  trying to load a calendar for which a backend type is not present.
 
 <!-- ##### ENUM CalClientGetStatus ##### -->
-<para>
+  <para>
+    These values describe the result of the cal_client_get_object()
+    function.
+  </para>
 
-</para>
+@CAL_CLIENT_GET_SUCCESS: Indicates a successful get operation.
+
+@CAL_CLIENT_GET_NOT_FOUND: Indicates that the requested object was
+  not found.
 
-@CAL_CLIENT_GET_SUCCESS: 
-@CAL_CLIENT_GET_NOT_FOUND: 
-@CAL_CLIENT_GET_SYNTAX_ERROR: 
+@CAL_CLIENT_GET_SYNTAX_ERROR: Indicates a syntax error when parsing
+  the requested object.  This could indicate a bug in the calendar
+  client libraries or in the Wombat server.
 
 <!-- ##### FUNCTION cal_client_new ##### -->
 <para>
@@ -180,26 +224,46 @@ CalClient
 
 
 <!-- ##### SIGNAL CalClient::cal-loaded ##### -->
-<para>
-
-</para>
-
-@calclient: the object which received the signal.
-@arg1: 
+  <para>
+    This signal is emitted some time after the calendar clients sends
+    a load or create request to the personal calendar server.  The
+    server will notify the client asynchronously of the completion of
+    the request.  The @status parameter indicates the status of the
+    request.
+  </para>
+
+@client: Calendar client which received the notification.
+@status: Status of the request.  See the description of
+  #CalClientLoadStatus for more details.
 
 <!-- ##### SIGNAL CalClient::obj-updated ##### -->
-<para>
+  <para>
+    This signal is emitted when the calendar clients receives
+    notification of a calendar component's data being changed in the
+    personal calendar server.  Graphical clients may want to get the
+    new version of the object and update their display, for example.
+  </para>
 
-</para>
-
-@calclient: the object which received the signal.
-@arg1: 
+@client: Calendar client which received the notification.
+@uid: Unique identifier of the calendar component that changed in the
+  personal calendar server's storage.
 
 <!-- ##### SIGNAL CalClient::obj-removed ##### -->
-<para>
-
-</para>
-
-@calclient: the object which received the signal.
-@arg1: 
-
+  <para>
+    This signal is emitted when the calendar client receives
+    notification for a calendar component being removed from the
+    storage in the personal calendar server.  Graphical clients may
+    want to delete the corresponding object from their display, for
+    example.
+  </para>
+
+@client: Calendar client which received the notification.
+@uid: Unique identifier of the calendar component that was removed
+  from the personal calendar server's storage.
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../../../evolution-devel-guide.sgml" "book" "refsect2" "")
+End:
+-->