GNOME.org
 

[evolution-data-server/openismus-work-3-8: 112/116] libebook: General documentation improvements

commit 7e0e2a7076cc54c3825a4fe0d6ce9c359d70d073
Author: Tristan Van Berkom <tristanvb openismus com>
Date:   Fri Aug 30 17:23:35 2013 +0200

    libebook: General documentation improvements
    
    Added documentation for EBookClientView signals, added main description
    sections to EBookClient & EBookClient, removed the documentation page
    for e-book-types and moved the remaining declarations to EBook (and
    properly marked those as deprecated).

 addressbook/libebook/e-book-client-cursor.c        |    1 +
 addressbook/libebook/e-book-client-view.c          |   69 ++++++++++++++++++++
 addressbook/libebook/e-book-client.c               |   17 +++++
 addressbook/libebook/e-book-types.h                |   16 ++++-
 addressbook/libebook/e-book-view.c                 |    9 +++
 addressbook/libebook/e-book.c                      |    3 +
 .../addressbook/libebook/libebook-docs.sgml        |    1 -
 .../addressbook/libebook/libebook-sections.txt     |    7 +-
 8 files changed, 117 insertions(+), 6 deletions(-)
---
diff --git a/addressbook/libebook/e-book-client-cursor.c b/addressbook/libebook/e-book-client-cursor.c
index 0c8fcf2..a19bdbc 100644
--- a/addressbook/libebook/e-book-client-cursor.c
+++ b/addressbook/libebook/e-book-client-cursor.c
@@ -22,6 +22,7 @@
  * SECTION: e-book-client-cursor
  * @include: libebook/libebook.h
  * @short_description: An addressbook cursor
+ * @See_Also: #EBookClient, #EBookClientView
  *
  * The #EBookClientCursor is an iteration based interface for browsing
  * a sorted list of contacts in the addressbook.
diff --git a/addressbook/libebook/e-book-client-view.c b/addressbook/libebook/e-book-client-view.c
index 275fa00..3388662 100644
--- a/addressbook/libebook/e-book-client-view.c
+++ b/addressbook/libebook/e-book-client-view.c
@@ -20,6 +20,33 @@
  * Author: Ross Burton <ross linux intel com>
  */
 
+/**
+ * SECTION: e-book-client-view
+ * @include: libebook/libebook.h
+ * @short_description: An addressbook view
+ * @See_Also: #EBookClient, #EBookClientCursor
+ *
+ * The #EBookClientView is a view for receiving change notifications for a
+ * given addressbook. Just use e_book_client_get_view() to obtain a filtered
+ * view of the addressbook.
+ *
+ * The view can be started and stopped with e_book_client_view_start() and
+ * e_book_client_view_stop(). After starting the view, notifications will be
+ * delivered for any changes in the contacts matching the specified filter via
+ * the #EBookClientView::objects-added, #EBookClientView::objects-modified and
+ * #EBookClientView::objects-removed signals.
+ *
+ * When initially starting the view, existing contacts which match the specified
+ * search expression will be added to the view and a series of #EBookClientView::objects-added
+ * signals and #EBookClientView::progress signals will be delivered during that time,
+ * until all of the matching contacts have been added to the view and the #EBookClientView::complete
+ * signal is fired.
+ *
+ * If you wish to avoid receiving the initial #EBookClientView::objects-added notifications
+ * at view startup time, then you can unset the %E_BOOK_CLIENT_VIEW_FLAGS_NOTIFY_INITIAL
+ * flag using e_book_client_view_set_flags() before starting up the view.
+ */
+
 #ifdef HAVE_CONFIG_H
 #include <config.h>
 #endif
@@ -988,6 +1015,13 @@ e_book_client_view_class_init (EBookClientViewClass *class)
                        G_PARAM_CONSTRUCT_ONLY |
                        G_PARAM_STATIC_STRINGS));
 
+       /**
+        * EBookClientView::objects-added:
+        * @view: The #EBookClientView emitting the signal
+        * @objects: A #GSList of #EContacts
+        *
+        * Notification signal that contacts have been added to the view
+        */
        signals[OBJECTS_ADDED] = g_signal_new (
                "objects-added",
                G_OBJECT_CLASS_TYPE (object_class),
@@ -998,6 +1032,13 @@ e_book_client_view_class_init (EBookClientViewClass *class)
                G_TYPE_NONE, 1,
                G_TYPE_POINTER);
 
+       /**
+        * EBookClientView::objects-modified:
+        * @view: The #EBookClientView emitting the signal
+        * @objects: A #GSList of #EContacts
+        *
+        * Notification signal that contacts have been modified in the view
+        */
        signals[OBJECTS_MODIFIED] = g_signal_new (
                "objects-modified",
                G_OBJECT_CLASS_TYPE (object_class),
@@ -1008,6 +1049,13 @@ e_book_client_view_class_init (EBookClientViewClass *class)
                G_TYPE_NONE, 1,
                G_TYPE_POINTER);
 
+       /**
+        * EBookClientView::objects-removed:
+        * @view: The #EBookClientView emitting the signal
+        * @objects: A #GSList of #EContacts
+        *
+        * Notification signal that contacts have been removed from the view
+        */
        signals[OBJECTS_REMOVED] = g_signal_new (
                "objects-removed",
                G_OBJECT_CLASS_TYPE (object_class),
@@ -1018,6 +1066,19 @@ e_book_client_view_class_init (EBookClientViewClass *class)
                G_TYPE_NONE, 1,
                G_TYPE_POINTER);
 
+       /**
+        * EBookClientView::progress:
+        * @view: The #EBookClientView emitting the signal
+        * @percent: The current percentage
+        * @message: A message about what is currently loading
+        *
+        * This notification signal is emitted periodically
+        * while loading the contacts in the specified view at
+        * view creation time.
+        *
+        * These progress messages are terminated with a
+        * #EBookClientView::complete signal.
+        */
        signals[PROGRESS] = g_signal_new (
                "progress",
                G_OBJECT_CLASS_TYPE (object_class),
@@ -1029,6 +1090,14 @@ e_book_client_view_class_init (EBookClientViewClass *class)
                G_TYPE_UINT,
                G_TYPE_STRING);
 
+       /**
+        * EBookClientView::complete:
+        * @view: The #EBookClientView emitting the signal
+        * @error: The error which occurred, if any
+        *
+        * This signal is emitted after loading the initial
+        * contacts when the view is created.
+        */
        signals[COMPLETE] = g_signal_new (
                "complete",
                G_OBJECT_CLASS_TYPE (object_class),
diff --git a/addressbook/libebook/e-book-client.c b/addressbook/libebook/e-book-client.c
index 14c44eb..176a064 100644
--- a/addressbook/libebook/e-book-client.c
+++ b/addressbook/libebook/e-book-client.c
@@ -20,6 +20,23 @@
  *
  */
 
+/**
+ * SECTION: e-book-client
+ * @include: libebook/libebook.h
+ * @short_description: The addressbook client
+ * @See_Also: #EBookClientView, #EBookClientCursor
+ *
+ * The #EBookClient is the main API used to interact with the Evolution Data Server's
+ * addressbook.
+ *
+ * In order to create an #EBookClient, you must first obtain the addressbook #ESource
+ * describing which addressbook you wish to connect to. #ESources can be obtained
+ * and created using the #ESourceRegistry API.
+ *
+ * Once you have obtained the #ESource describing your addressbook, use e_book_client_connect()
+ * or e_book_client_connect_direct() to interact with the selected addressbook.
+ */
+
 #ifdef HAVE_CONFIG_H
 #include <config.h>
 #endif
diff --git a/addressbook/libebook/e-book-types.h b/addressbook/libebook/e-book-types.h
index 0f55343..6dbfed1 100644
--- a/addressbook/libebook/e-book-types.h
+++ b/addressbook/libebook/e-book-types.h
@@ -20,10 +20,19 @@
 
 G_BEGIN_DECLS
 
+/**
+ * E_BOOK_ERROR:
+ *
+ * Deprecated: 3.2: Use #EBookClient apis instead
+ */
 #define E_BOOK_ERROR e_book_error_quark()
-
 GQuark e_book_error_quark (void) G_GNUC_CONST;
 
+/**
+ * EBookStatus:
+ *
+ * Deprecated: 3.2: Use #EBookClient apis instead
+ */
 typedef enum {
        E_BOOK_ERROR_OK,
        E_BOOK_ERROR_INVALID_ARG,
@@ -52,6 +61,11 @@ typedef enum {
        E_BOOK_ERROR_NOT_SUPPORTED
 } EBookStatus;
 
+/**
+ * E_BOOK_ERROR_CORBA_EXCEPTION:
+ *
+ * Deprecated: 3.2: Use #EBookClient apis instead
+ */
 #ifndef E_BOOK_DISABLE_DEPRECATED
 #define E_BOOK_ERROR_CORBA_EXCEPTION E_BOOK_ERROR_DBUS_EXCEPTION
 #endif
diff --git a/addressbook/libebook/e-book-view.c b/addressbook/libebook/e-book-view.c
index 19c9adf..a2f62c1 100644
--- a/addressbook/libebook/e-book-view.c
+++ b/addressbook/libebook/e-book-view.c
@@ -20,6 +20,15 @@
  * Author: Ross Burton <ross linux intel com>
  */
 
+/**
+ * SECTION:e-book-view
+ * @short_description: The deprecated addressbook view API
+ *
+ * This deprecated API was replaced with #EBookClientView.
+ *
+ * Deprecated: 3.2: Use #EBookClientView instead.
+ */
+
 #include "e-book.h"
 #include "e-book-view.h"
 #include "e-book-view-private.h"
diff --git a/addressbook/libebook/e-book.c b/addressbook/libebook/e-book.c
index 8b25fd1..918ef91 100644
--- a/addressbook/libebook/e-book.c
+++ b/addressbook/libebook/e-book.c
@@ -24,6 +24,9 @@
 
 /**
  * SECTION:e-book
+ * @short_description: The deprecated addressbook API
+ *
+ * This deprecated API was replaced with #EBookClient.
  *
  * The old asynchronous API was deprecated since 3.0 and is replaced with
  * their an equivalent version which has a detailed #GError
diff --git a/docs/reference/addressbook/libebook/libebook-docs.sgml 
b/docs/reference/addressbook/libebook/libebook-docs.sgml
index 4ab5ff5..630bee9 100644
--- a/docs/reference/addressbook/libebook/libebook-docs.sgml
+++ b/docs/reference/addressbook/libebook/libebook-docs.sgml
@@ -13,7 +13,6 @@
     <xi:include href="xml/e-book-client.xml"/>
     <xi:include href="xml/e-book-client-view.xml"/>
     <xi:include href="xml/e-book-client-cursor.xml"/>
-    <xi:include href="xml/e-book-types.xml"/>
     <xi:include href="xml/e-destination.xml"/>
   </chapter>
 
diff --git a/docs/reference/addressbook/libebook/libebook-sections.txt 
b/docs/reference/addressbook/libebook/libebook-sections.txt
index 0d2452f..b8d991a 100644
--- a/docs/reference/addressbook/libebook/libebook-sections.txt
+++ b/docs/reference/addressbook/libebook/libebook-sections.txt
@@ -21,6 +21,8 @@ EBookViewPrivate
 <SECTION>
 <FILE>e-book</FILE>
 <TITLE>EBook</TITLE>
+E_BOOK_ERROR
+EBookStatus
 EBook
 e_book_new
 e_book_remove
@@ -105,6 +107,7 @@ E_BOOK_GET_CLASS
 e_book_get_type
 <SUBSECTION Private>
 EBookPrivate
+e_book_error_quark
 </SECTION>
 
 <SECTION>
@@ -233,11 +236,7 @@ EBookClientViewPrivate
 
 <SECTION>
 <FILE>e-book-types</FILE>
-E_BOOK_ERROR
-e_book_error_quark
-EBookStatus
 <SUBSECTION Deprecated>
-E_BOOK_ERROR_CORBA_EXCEPTION
 </SECTION>
 
 <SECTION>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]