GNOME.org
 

[evolution-data-server/documentation-effort: 5/18] libedata-book: Deprecating older versions of the vcard storages and summaries.

commit d10426bf8dcce7d6ac1504a8eb39ddfb1f87c4f2
Author: Tristan Van Berkom <tristanvb openismus com>
Date:   Sat Nov 30 20:58:39 2013 +0900

    libedata-book: Deprecating older versions of the vcard storages and summaries.
    
    Now recommend usage of EBookSqlite instead of these older classes.
    
    Also added documentation headers to all classes in libedata-book.

 addressbook/libedata-book/e-book-backend-cache.c   |   25 +++++
 addressbook/libedata-book/e-book-backend-cache.h   |    8 ++
 .../libedata-book/e-book-backend-db-cache.c        |   34 +++++++
 .../libedata-book/e-book-backend-db-cache.h        |    4 +
 addressbook/libedata-book/e-book-backend-factory.c |    9 ++
 addressbook/libedata-book/e-book-backend-sexp.c    |    8 ++
 .../libedata-book/e-book-backend-sqlitedb.c        |  104 +++++++++++++++++++-
 .../libedata-book/e-book-backend-sqlitedb.h        |   22 ++++-
 addressbook/libedata-book/e-book-backend-summary.c |   29 ++++++
 addressbook/libedata-book/e-book-backend-summary.h |    4 +
 addressbook/libedata-book/e-book-backend.c         |    9 ++
 addressbook/libedata-book/e-data-book-direct.c     |   14 +++
 addressbook/libedata-book/e-data-book-factory.c    |    9 ++
 addressbook/libedata-book/e-data-book-view.c       |   12 +++
 addressbook/libedata-book/e-data-book.c            |    9 ++
 15 files changed, 295 insertions(+), 5 deletions(-)
---
diff --git a/addressbook/libedata-book/e-book-backend-cache.c 
b/addressbook/libedata-book/e-book-backend-cache.c
index 00e0206..6fee8d9 100644
--- a/addressbook/libedata-book/e-book-backend-cache.c
+++ b/addressbook/libedata-book/e-book-backend-cache.c
@@ -19,6 +19,13 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION: e-book-backend-cache
+ * @include: libedata-book/libedata-book.h
+ * @short_description: A utility for storing contact data and searching for contacts
+ *
+ * The #EBookBackendCache is deprecated, use #EBookSqlite instead.
+ */
 #ifdef HAVE_CONFIG_H
 #include <config.h>
 #endif
@@ -58,6 +65,8 @@ e_book_backend_cache_init (EBookBackendCache *cache)
  * #EContact objects, useful for remote backends.
  *
  * Returns: a new #EBookBackendCache
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  */
 EBookBackendCache *
 e_book_backend_cache_new (const gchar *filename)
@@ -79,6 +88,8 @@ e_book_backend_cache_new (const gchar *filename)
  * needed.
  *
  * Returns: A cached #EContact, or %NULL if @uid is not cached.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 EContact *
 e_book_backend_cache_get_contact (EBookBackendCache *cache,
@@ -107,6 +118,8 @@ e_book_backend_cache_get_contact (EBookBackendCache *cache,
  * Adds @contact to @cache.
  *
  * Returns: %TRUE if the contact was cached successfully, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_cache_add_contact (EBookBackendCache *cache,
@@ -139,6 +152,8 @@ e_book_backend_cache_add_contact (EBookBackendCache *cache,
  * Removes the contact identified by @uid from @cache.
  *
  * Returns: %TRUE if the contact was found and removed, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_cache_remove_contact (EBookBackendCache *cache,
@@ -162,6 +177,8 @@ e_book_backend_cache_remove_contact (EBookBackendCache *cache,
  * Checks if the contact identified by @uid exists in @cache.
  *
  * Returns: %TRUE if the cache contains the contact, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_cache_check_contact (EBookBackendCache *cache,
@@ -189,6 +206,8 @@ e_book_backend_cache_check_contact (EBookBackendCache *cache,
  * free the list.
  *
  * Returns: A #GList of pointers to #EContact.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 GList *
 e_book_backend_cache_get_contacts (EBookBackendCache *cache,
@@ -240,6 +259,8 @@ e_book_backend_cache_get_contacts (EBookBackendCache *cache,
  * free the ID strings and the array.
  *
  * Returns: A #GPtrArray of pointers to contact ID strings.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 GPtrArray *
 e_book_backend_cache_search (EBookBackendCache *cache,
@@ -267,6 +288,8 @@ e_book_backend_cache_search (EBookBackendCache *cache,
  *
  * Flags @cache as being populated - that is, it is up-to-date on the
  * contents of the book it's caching.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 void
 e_book_backend_cache_set_populated (EBookBackendCache *cache)
@@ -282,6 +305,8 @@ e_book_backend_cache_set_populated (EBookBackendCache *cache)
  * Checks if @cache is populated.
  *
  * Returns: %TRUE if @cache is populated, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_cache_is_populated (EBookBackendCache *cache)
diff --git a/addressbook/libedata-book/e-book-backend-cache.h 
b/addressbook/libedata-book/e-book-backend-cache.h
index 9b21a0f..f977d4b 100644
--- a/addressbook/libedata-book/e-book-backend-cache.h
+++ b/addressbook/libedata-book/e-book-backend-cache.h
@@ -27,6 +27,8 @@
 #ifndef E_BOOK_BACKEND_CACHE_H
 #define E_BOOK_BACKEND_CACHE_H
 
+#ifndef EDS_DISABLE_DEPRECATED
+
 #include <libebook-contacts/libebook-contacts.h>
 #include <libebackend/libebackend.h>
 
@@ -60,6 +62,8 @@ typedef struct _EBookBackendCachePrivate EBookBackendCachePrivate;
  *
  * Contains only private data that should be read and manipulated using the
  * functions below.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  */
 struct _EBookBackendCache {
        /*< private >*/
@@ -71,6 +75,8 @@ struct _EBookBackendCache {
  * EBookBackendCacheClass:
  *
  * Class structure for the #EBookBackendCache class.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  */
 struct _EBookBackendCacheClass {
        /*< private >*/
@@ -105,4 +111,6 @@ GPtrArray * e_book_backend_cache_search     (EBookBackendCache *cache,
 
 G_END_DECLS
 
+#endif /* EDS_DISABLE_DEPRECATED */
+
 #endif /* E_BOOK_BACKEND_CACHE_H */
diff --git a/addressbook/libedata-book/e-book-backend-db-cache.c 
b/addressbook/libedata-book/e-book-backend-db-cache.c
index 4d98a84..fc1bc1a 100644
--- a/addressbook/libedata-book/e-book-backend-db-cache.c
+++ b/addressbook/libedata-book/e-book-backend-db-cache.c
@@ -19,6 +19,14 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  */
 
+/**
+ * SECTION: e-book-backend-db-cache
+ * @include: libedata-book/libedata-book.h
+ * @short_description: A Berkeley DB cache facility for addressbooks
+ *
+ * This API is deprecated, use #EBookSqlite instead.
+ */
+
 #include <config.h>
 #include <stdlib.h>
 #include <string.h>
@@ -65,6 +73,8 @@ get_filename_from_uri (const gchar *uri)
  * @filename: filename to be set
  *
  * Set the filename for db cacahe file.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 
 void
@@ -89,6 +99,8 @@ e_book_backend_db_cache_set_filename (DB *db,
  * @db:  DB Handle
  *
  * Get the filename for db cacahe file.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 
 gchar *
@@ -124,6 +136,8 @@ e_book_backend_db_cache_get_filename (DB *db)
  * needed.
  *
  * Returns: A cached #EContact, or %NULL if @uid is not cached.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 EContact *
 e_book_backend_db_cache_get_contact (DB *db,
@@ -158,6 +172,8 @@ e_book_backend_db_cache_get_contact (DB *db,
  * Adds @contact to @cache.
  *
  * Returns: %TRUE if the contact was cached successfully, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_db_cache_add_contact (DB *db,
@@ -203,6 +219,8 @@ e_book_backend_db_cache_add_contact (DB *db,
  * Removes the contact identified by @uid from @cache.
  *
  * Returns: %TRUE if the contact was found and removed, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_db_cache_remove_contact (DB *db,
@@ -234,6 +252,8 @@ e_book_backend_db_cache_remove_contact (DB *db,
  * Checks if the contact identified by @uid exists in @cache.
  *
  * Returns: %TRUE if the cache contains the contact, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_db_cache_check_contact (DB *db,
@@ -267,6 +287,8 @@ e_book_backend_db_cache_check_contact (DB *db,
  * free the list.
  *
  * Returns: A #GList of pointers to #EContact.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 GList *
 e_book_backend_db_cache_get_contacts (DB *db,
@@ -329,6 +351,8 @@ e_book_backend_db_cache_get_contacts (DB *db,
  * free the ID strings and the array.
  *
  * Returns: A #GPtrArray of pointers to contact ID strings.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 GPtrArray *
 e_book_backend_db_cache_search (DB *db,
@@ -357,6 +381,8 @@ e_book_backend_db_cache_search (DB *db,
  * Checks if an #EBookBackendCache exists at @uri.
  *
  * Returns: %TRUE if cache exists, %FALSE if not.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_db_cache_exists (const gchar *uri)
@@ -379,6 +405,8 @@ e_book_backend_db_cache_exists (const gchar *uri)
  *
  * Flags @cache as being populated - that is, it is up-to-date on the
  * contents of the book it's caching.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 void
 e_book_backend_db_cache_set_populated (DB *db)
@@ -402,6 +430,8 @@ e_book_backend_db_cache_set_populated (DB *db)
  * Checks if @cache is populated.
  *
  * Returns: %TRUE if @cache is populated, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_db_cache_is_populated (DB *db)
@@ -429,6 +459,8 @@ e_book_backend_db_cache_is_populated (DB *db)
  * @t: The time in string format
  *
  * Since: 2.26
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 void
 e_book_backend_db_cache_set_time (DB *db,
@@ -451,6 +483,8 @@ e_book_backend_db_cache_set_time (DB *db,
  * @db: A Berkeley DB handle
  *
  * Since: 2.26
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gchar *
 e_book_backend_db_cache_get_time (DB *db)
diff --git a/addressbook/libedata-book/e-book-backend-db-cache.h 
b/addressbook/libedata-book/e-book-backend-db-cache.h
index 41c47fb..fcb2dfc 100644
--- a/addressbook/libedata-book/e-book-backend-db-cache.h
+++ b/addressbook/libedata-book/e-book-backend-db-cache.h
@@ -26,6 +26,8 @@
 #ifndef E_BOOK_BACKEND_DB_CACHE_H
 #define E_BOOK_BACKEND_DB_CACHE_H
 
+#ifndef EDS_DISABLE_DEPRECATED
+
 #include <libebook-contacts/libebook-contacts.h>
 
 G_BEGIN_DECLS
@@ -68,5 +70,7 @@ gchar *               e_book_backend_db_cache_get_time
 
 G_END_DECLS
 
+#endif /* EDS_DISABLE_DEPRECATED */
+
 #endif /* E_BOOK_BACKEND_DB_CACHE_H */
 
diff --git a/addressbook/libedata-book/e-book-backend-factory.c 
b/addressbook/libedata-book/e-book-backend-factory.c
index e63c173..296c13c 100644
--- a/addressbook/libedata-book/e-book-backend-factory.c
+++ b/addressbook/libedata-book/e-book-backend-factory.c
@@ -7,6 +7,15 @@
  * Copyright (C) 1999-2008 Novell, Inc. (www.novell.com)
  */
 
+/**
+ * SECTION: e-book-backend-factory
+ * @include: libedata-book/libedata-book.h
+ * @short_description: The factory for creating new addressbooks
+ *
+ * This class handles creation of new addressbooks of various
+ * backend types.
+ **/
+
 #include <config.h>
 
 #include "e-book-backend.h"
diff --git a/addressbook/libedata-book/e-book-backend-sexp.c b/addressbook/libedata-book/e-book-backend-sexp.c
index 6bcd13f..51da41a 100644
--- a/addressbook/libedata-book/e-book-backend-sexp.c
+++ b/addressbook/libedata-book/e-book-backend-sexp.c
@@ -23,6 +23,14 @@
  * 02110-1301, USA.
  */
 
+
+/**
+ * SECTION: e-book-backend-sexp
+ * @include: libedata-book/libedata-book.h
+ * @short_description: A utility for comparing #EContacts or vcards with search expressions.
+ *
+ * This API is an all purpose utility for comparing #EContacts with search expressions generated by 
#EBookQuery.
+ */
 #include "e-book-backend-sexp.h"
 
 #include <glib/gi18n.h>
diff --git a/addressbook/libedata-book/e-book-backend-sqlitedb.c 
b/addressbook/libedata-book/e-book-backend-sqlitedb.c
index 384c6de..296c88c 100644
--- a/addressbook/libedata-book/e-book-backend-sqlitedb.c
+++ b/addressbook/libedata-book/e-book-backend-sqlitedb.c
@@ -22,6 +22,15 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  */
 
+
+/**
+ * SECTION: e-book-backend-sqlitedb
+ * @include: libedata-book/libedata-book.h
+ * @short_description: An SQLite storage facility for addressbooks
+ *
+ * The #EBookBackendSqliteDB is deprecated, use #EBookSqlite instead.
+ */
+
 #include "e-book-backend-sqlitedb.h"
 
 #include <locale.h>
@@ -62,6 +71,15 @@
 #endif
 
 #define DB_FILENAME "contacts.db"
+
+/* WARNING:
+ *
+ * FOLDER_VERSION can NEVER be incremented again.
+ *
+ * This class is deprecated and the continuation of this
+ * very same folder version can be found in EBookSqlite,
+ * use EBookSqlite instead.
+ */
 #define FOLDER_VERSION 7
 
 typedef enum {
@@ -1790,6 +1808,8 @@ summary_fields_add_indexes (GArray *array,
  * Returns: (transfer full): The newly created #EBookBackendSqliteDB
  *
  * Since: 3.8
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 EBookBackendSqliteDB *
 e_book_backend_sqlitedb_new_full (const gchar *path,
@@ -1881,6 +1901,8 @@ e_book_backend_sqlitedb_new_full (const gchar *path,
  * Returns: (transfer full): A reference to a #EBookBackendSqliteDB
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 EBookBackendSqliteDB *
 e_book_backend_sqlitedb_new (const gchar *path,
@@ -1970,6 +1992,8 @@ e_book_backend_sqlitedb_unlock_updates (EBookBackendSqliteDB *ebsdb,
  * Note that the active collator will change with the active locale setting.
  *
  * Returns: (transfer full): A reference to the active collator.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  */
 ECollator *
 e_book_backend_sqlitedb_ref_collator(EBookBackendSqliteDB *ebsdb)
@@ -2370,6 +2394,8 @@ insert_contact (EBookBackendSqliteDB *ebsdb,
  * Returns: TRUE on success.
  *
  * Since: 3.8
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_sqlitedb_new_contact (EBookBackendSqliteDB *ebsdb,
@@ -2407,6 +2433,8 @@ e_book_backend_sqlitedb_new_contact (EBookBackendSqliteDB *ebsdb,
  * Returns: TRUE on success.
  *
  * Since: 3.8
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_sqlitedb_new_contacts (EBookBackendSqliteDB *ebsdb,
@@ -2474,7 +2502,7 @@ e_book_backend_sqlitedb_new_contacts (EBookBackendSqliteDB *ebsdb,
  *
  * Since: 3.2
  *
- * Deprecated: 3.8: Use e_book_backend_sqlitedb_new_contact() instead.
+ * Deprecated: 3.8: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_sqlitedb_add_contact (EBookBackendSqliteDB *ebsdb,
@@ -2499,7 +2527,7 @@ e_book_backend_sqlitedb_add_contact (EBookBackendSqliteDB *ebsdb,
  *
  * Since: 3.2
  *
- * Deprecated: 3.8: Use e_book_backend_sqlitedb_new_contacts() instead.
+ * Deprecated: 3.8: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_sqlitedb_add_contacts (EBookBackendSqliteDB *ebsdb,
@@ -2523,6 +2551,8 @@ e_book_backend_sqlitedb_add_contacts (EBookBackendSqliteDB *ebsdb,
  * Returns: %TRUE on success, otherwise %FALSE is returned and @error is set appropriately.
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_sqlitedb_remove_contact (EBookBackendSqliteDB *ebsdb,
@@ -2599,6 +2629,8 @@ generate_delete_stmt (const gchar *table,
  * Returns: %TRUE on success, otherwise %FALSE is returned and @error is set appropriately.
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_sqlitedb_remove_contacts (EBookBackendSqliteDB *ebsdb,
@@ -2679,6 +2711,8 @@ contact_found_cb (gpointer ref,
  * it was set by this function.</para></note>
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_sqlitedb_has_contact (EBookBackendSqliteDB *ebsdb,
@@ -2752,6 +2786,8 @@ get_vcard_cb (gpointer ref,
  * returned if there was an error or if no contact was found for @uid.
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 EContact *
 e_book_backend_sqlitedb_get_contact (EBookBackendSqliteDB *ebsdb,
@@ -2811,7 +2847,7 @@ uid_rev_fields (GHashTable *fields_of_interest)
  *
  * Since: 3.2
  *
- * Deprecated: 3.8: Use e_book_backend_sqlitedb_check_summary_fields() instead.
+ * Deprecated: 3.8: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_sqlitedb_is_summary_fields (GHashTable *fields_of_interest)
@@ -2862,6 +2898,8 @@ e_book_backend_sqlitedb_is_summary_fields (GHashTable *fields_of_interest)
  * in the summary.
  *
  * Since: 3.8
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_sqlitedb_check_summary_fields (EBookBackendSqliteDB *ebsdb,
@@ -2968,6 +3006,8 @@ store_data_to_vcard (gpointer ref,
  * Returns: (transfer full): The vcard string for @uid or %NULL if @uid was not found.
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  */
 gchar *
 e_book_backend_sqlitedb_get_vcard_string (EBookBackendSqliteDB *ebsdb,
@@ -3308,6 +3348,8 @@ e_book_backend_sqlitedb_check_summary_query_locked (EBookBackendSqliteDB *ebsdb,
  * Returns: %TRUE if @query contains only fields configured in the summary.
  *
  * Since: 3.8
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_sqlitedb_check_summary_query (EBookBackendSqliteDB *ebsdb,
@@ -3336,6 +3378,8 @@ e_book_backend_sqlitedb_check_summary_query (EBookBackendSqliteDB *ebsdb,
  * Since: 3.2
  *
  * Deprecated: 3.8: Use e_book_backend_sqlitedb_check_summary_query() instead
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_sqlitedb_is_summary_query (const gchar *query)
@@ -4210,6 +4254,8 @@ book_backend_sqlitedb_search_full (EBookBackendSqliteDB *ebsdb,
  * Returns: (transfer full): A #GSList of #EbSdbSearchData structures.
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 GSList *
 e_book_backend_sqlitedb_search (EBookBackendSqliteDB *ebsdb,
@@ -4303,6 +4349,8 @@ e_book_backend_sqlitedb_search (EBookBackendSqliteDB *ebsdb,
  * Returns: (transfer full): A #GSList of allocated contact UID strings.
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 GSList *
 e_book_backend_sqlitedb_search_uids (EBookBackendSqliteDB *ebsdb,
@@ -4423,6 +4471,8 @@ get_uids_and_rev_cb (gpointer user_data,
  * Returns: (transfer full): A #GHashTable of all contact revisions by UID.
  *
  * Since: 3.4
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 GHashTable *
 e_book_backend_sqlitedb_get_uids_and_rev (EBookBackendSqliteDB *ebsdb,
@@ -4465,6 +4515,8 @@ e_book_backend_sqlitedb_get_uids_and_rev (EBookBackendSqliteDB *ebsdb,
  * Returns: Whether the 'is populated' flag is set.
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_sqlitedb_get_is_populated (EBookBackendSqliteDB *ebsdb,
@@ -4504,6 +4556,8 @@ e_book_backend_sqlitedb_get_is_populated (EBookBackendSqliteDB *ebsdb,
  * Returns: %TRUE on success, otherwise %FALSE is returned and @error is set appropriately. 
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_sqlitedb_set_is_populated (EBookBackendSqliteDB *ebsdb,
@@ -4555,6 +4609,8 @@ e_book_backend_sqlitedb_set_is_populated (EBookBackendSqliteDB *ebsdb,
  * Returns: %TRUE on success, otherwise %FALSE is returned and @error is set appropriately. 
  *
  * Since: 3.8
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  */
 gboolean
 e_book_backend_sqlitedb_get_revision (EBookBackendSqliteDB *ebsdb,
@@ -4594,6 +4650,8 @@ e_book_backend_sqlitedb_get_revision (EBookBackendSqliteDB *ebsdb,
  * Returns: %TRUE on success, otherwise %FALSE is returned and @error is set appropriately. 
  *
  * Since: 3.8
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  */
 gboolean
 e_book_backend_sqlitedb_set_revision (EBookBackendSqliteDB *ebsdb,
@@ -4650,6 +4708,8 @@ e_book_backend_sqlitedb_set_revision (EBookBackendSqliteDB *ebsdb,
  * Returns: %TRUE if the vcards stored in the db were downloaded partially.
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_sqlitedb_get_has_partial_content (EBookBackendSqliteDB *ebsdb,
@@ -4688,6 +4748,8 @@ e_book_backend_sqlitedb_get_has_partial_content (EBookBackendSqliteDB *ebsdb,
  * Returns: %TRUE on success, otherwise %FALSE is returned and @error is set appropriately. 
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_sqlitedb_set_has_partial_content (EBookBackendSqliteDB *ebsdb,
@@ -4742,6 +4804,8 @@ e_book_backend_sqlitedb_set_has_partial_content (EBookBackendSqliteDB *ebsdb,
  * Returns: (transfer full): The extra data previously set for @uid, or %NULL
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gchar *
 e_book_backend_sqlitedb_get_contact_bdata (EBookBackendSqliteDB *ebsdb,
@@ -4787,6 +4851,8 @@ e_book_backend_sqlitedb_get_contact_bdata (EBookBackendSqliteDB *ebsdb,
  * Returns: %TRUE on success, otherwise %FALSE is returned and @error is set appropriately. 
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_sqlitedb_set_contact_bdata (EBookBackendSqliteDB *ebsdb,
@@ -4839,6 +4905,8 @@ e_book_backend_sqlitedb_set_contact_bdata (EBookBackendSqliteDB *ebsdb,
  * Returns: (transfer full): The data previously set with e_book_backend_sqlitedb_set_sync_data().
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gchar *
 e_book_backend_sqlitedb_get_sync_data (EBookBackendSqliteDB *ebsdb,
@@ -4876,6 +4944,8 @@ e_book_backend_sqlitedb_get_sync_data (EBookBackendSqliteDB *ebsdb,
  * Returns: %TRUE on success, otherwise %FALSE is returned and @error is set appropriately. 
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_sqlitedb_set_sync_data (EBookBackendSqliteDB *ebsdb,
@@ -4928,6 +4998,8 @@ e_book_backend_sqlitedb_set_sync_data (EBookBackendSqliteDB *ebsdb,
  * Returns: (transfer full): The data previously set with e_book_backend_sqlitedb_set_key_value().
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gchar *
 e_book_backend_sqlitedb_get_key_value (EBookBackendSqliteDB *ebsdb,
@@ -4968,6 +5040,8 @@ e_book_backend_sqlitedb_get_key_value (EBookBackendSqliteDB *ebsdb,
  * Returns: %TRUE on success, otherwise %FALSE is returned and @error is set appropriately. 
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_sqlitedb_set_key_value (EBookBackendSqliteDB *ebsdb,
@@ -5020,6 +5094,8 @@ e_book_backend_sqlitedb_set_key_value (EBookBackendSqliteDB *ebsdb,
  * Returns: %NULL
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 GSList *
 e_book_backend_sqlitedb_get_partially_cached_ids (EBookBackendSqliteDB *ebsdb,
@@ -5057,6 +5133,8 @@ e_book_backend_sqlitedb_get_partially_cached_ids (EBookBackendSqliteDB *ebsdb,
  * Returns: %TRUE on success, otherwise %FALSE is returned and @error is set appropriately. 
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_sqlitedb_delete_addressbook (EBookBackendSqliteDB *ebsdb,
@@ -5126,6 +5204,8 @@ rollback:
  * Frees an #EbSdbSearchData
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 void
 e_book_backend_sqlitedb_search_data_free (EbSdbSearchData *s_data)
@@ -5286,6 +5366,8 @@ sqlitedb_set_locale_internal (EBookBackendSqliteDB *ebsdb,
  * Returns: Whether the new locale was successfully set.
  *
  * Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  */
 gboolean
 e_book_backend_sqlitedb_set_locale (EBookBackendSqliteDB *ebsdb,
@@ -5370,6 +5452,8 @@ e_book_backend_sqlitedb_set_locale (EBookBackendSqliteDB *ebsdb,
  * Returns: Whether the locale was successfully fetched.
  *
  * Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  */
 gboolean
 e_book_backend_sqlitedb_get_locale (EBookBackendSqliteDB *ebsdb,
@@ -5911,6 +5995,8 @@ cursor_count_position_locked (EBookBackendSqliteDB *ebsdb,
  * Returns: (transfer full): A newly created #EbSdbCursor
  *
  * Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  */
 EbSdbCursor *
 e_book_backend_sqlitedb_cursor_new (EBookBackendSqliteDB *ebsdb,
@@ -5976,6 +6062,8 @@ e_book_backend_sqlitedb_cursor_new (EBookBackendSqliteDB *ebsdb,
  * Frees @cursor.
  *
  * Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  */
 void
 e_book_backend_sqlitedb_cursor_free (EBookBackendSqliteDB *ebsdb,
@@ -6056,6 +6144,8 @@ collect_results_for_cursor_cb (gpointer ref,
  * returned and @error is set.
  *
  * Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  */
 gint
 e_book_backend_sqlitedb_cursor_step (EBookBackendSqliteDB *ebsdb,
@@ -6262,6 +6352,8 @@ e_book_backend_sqlitedb_cursor_step (EBookBackendSqliteDB *ebsdb,
  * Use e_book_backend_sqlitedb_ref_collator() to obtain the active collator for @ebsdb.
  *
  * Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  */
 void
 e_book_backend_sqlitedb_cursor_set_target_alphabetic_index (EBookBackendSqliteDB *ebsdb,
@@ -6301,6 +6393,8 @@ e_book_backend_sqlitedb_cursor_set_target_alphabetic_index (EBookBackendSqliteDB
  * Returns: %TRUE if the expression was valid and accepted by @ebsdb
  *
  * Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  */
 gboolean
 e_book_backend_sqlitedb_cursor_set_sexp (EBookBackendSqliteDB *ebsdb,
@@ -6346,6 +6440,8 @@ e_book_backend_sqlitedb_cursor_set_sexp (EBookBackendSqliteDB *ebsdb,
  * Returns: Whether @total and @position were successfully calculated.
  *
  * Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  */
 gboolean
 e_book_backend_sqlitedb_cursor_calculate (EBookBackendSqliteDB *ebsdb,
@@ -6427,6 +6523,8 @@ e_book_backend_sqlitedb_cursor_calculate (EBookBackendSqliteDB *ebsdb,
  * respectively, to be less than, to match, or be greater than the current value of @cursor.
  *
  * Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  */
 gint
 e_book_backend_sqlitedb_cursor_compare_contact (EBookBackendSqliteDB *ebsdb,
diff --git a/addressbook/libedata-book/e-book-backend-sqlitedb.h 
b/addressbook/libedata-book/e-book-backend-sqlitedb.h
index 8036c1c..c17e4d7 100644
--- a/addressbook/libedata-book/e-book-backend-sqlitedb.h
+++ b/addressbook/libedata-book/e-book-backend-sqlitedb.h
@@ -29,6 +29,8 @@
 #ifndef E_BOOK_BACKEND_SQLITEDB_H
 #define E_BOOK_BACKEND_SQLITEDB_H
 
+#ifndef EDS_DISABLE_DEPRECATED
+
 #include <libebook-contacts/libebook-contacts.h>
 
 /* Standard GObject macros */
@@ -56,6 +58,8 @@
  * Error domain for #EBookBackendSqliteDB operations.
  *
  * Since: 3.8
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 #define E_BOOK_SDB_ERROR (e_book_backend_sqlitedb_error_quark ())
 
@@ -77,6 +81,8 @@ typedef struct _EBookBackendSqliteDBPrivate EBookBackendSqliteDBPrivate;
  * @E_BOOK_SDB_ERROR_END_OF_LIST: An attempt was made to fetch results past the end of a contact list
  *
  * Defines the types of possible errors reported by the #EBookBackendSqliteDB
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  */
 typedef enum {
        E_BOOK_SDB_ERROR_CONSTRAINT,
@@ -94,6 +100,8 @@ typedef enum {
  * functions below.
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 struct _EBookBackendSqliteDB {
        /*< private >*/
@@ -105,6 +113,8 @@ struct _EBookBackendSqliteDB {
  * EBookBackendSqliteDBClass:
  *
  * Class structure for the #EBookBackendSqlite class.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  */
 struct _EBookBackendSqliteDBClass {
        /*< private >*/
@@ -127,6 +137,8 @@ struct _EBookBackendSqliteDBClass {
  * These should be freed with e_book_backend_sqlitedb_search_data_free().
  *
  * Since: 3.2
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 typedef struct {
        gchar *vcard;
@@ -140,6 +152,8 @@ typedef struct {
  * An opaque cursor pointer
  *
  * Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  */
 typedef struct _EbSdbCursor EbSdbCursor;
 
@@ -156,6 +170,8 @@ typedef struct _EbSdbCursor EbSdbCursor;
  * is the same as %EBSDB_CURSOR_ORIGIN_BEGIN.
  *
  * Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  */
 typedef enum {
        EBSDB_CURSOR_ORIGIN_CURRENT = 0,
@@ -171,6 +187,8 @@ typedef enum {
  * Defines the behaviour of e_book_backend_sqlitedb_cursor_step().
  *
  * Since: 3.12
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  */
 typedef enum {
        EBSDB_CURSOR_STEP_MOVE  = (1 << 0),
@@ -395,7 +413,6 @@ gint            e_book_backend_sqlitedb_cursor_compare_contact
                                                 EContact             *contact,
                                                 gboolean             *matches_sexp);
 
-#ifndef EDS_DISABLE_DEPRECATED
 gboolean       e_book_backend_sqlitedb_is_summary_query
                                                (const gchar *query);
 gboolean       e_book_backend_sqlitedb_is_summary_fields
@@ -412,8 +429,9 @@ gboolean    e_book_backend_sqlitedb_add_contacts
                                                 GSList *contacts,
                                                 gboolean partial_content,
                                                 GError **error);
-#endif
 
 G_END_DECLS
 
+#endif /* EDS_DISABLE_DEPRECATED */
+
 #endif /* E_BOOK_BACKEND_SQLITEDB_H */
diff --git a/addressbook/libedata-book/e-book-backend-summary.c 
b/addressbook/libedata-book/e-book-backend-summary.c
index c41ee69..686391e 100644
--- a/addressbook/libedata-book/e-book-backend-summary.c
+++ b/addressbook/libedata-book/e-book-backend-summary.c
@@ -21,6 +21,13 @@
  * 02110-1301, USA.
  */
 
+/**
+ * SECTION: e-book-backend-summary
+ * @include: libedata-book/libedata-book.h
+ * @short_description: A utility for storing contact data and searching for contacts
+ *
+ * The #EBookBackendSummary is deprecated, use #EBookSqlite instead.
+ */
 #ifdef HAVE_CONFIG_H
 #include <config.h>
 #endif
@@ -153,6 +160,8 @@ clear_items (EBookBackendSummary *summary)
  * the summary is changed until it is flushed to disk.
  *
  * Returns: A new #EBookBackendSummary.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 EBookBackendSummary *
 e_book_backend_summary_new (const gchar *summary_path,
@@ -483,6 +492,8 @@ e_book_backend_summary_open (EBookBackendSummary *summary)
  * not out of date.
  *
  * Returns: %TRUE if the load succeeded, %FALSE if it failed.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_summary_load (EBookBackendSummary *summary)
@@ -640,6 +651,8 @@ e_book_backend_summary_save_item (EBookBackendSummary *summary,
  * Attempts to save @summary to disk.
  *
  * Returns: %TRUE if the save succeeded, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_summary_save (EBookBackendSummary *summary)
@@ -723,6 +736,8 @@ e_book_backend_summary_save (EBookBackendSummary *summary)
  *
  * Adds a summary of @contact to @summary. Does not check if
  * the contact already has a summary.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 void
 e_book_backend_summary_add_contact (EBookBackendSummary *summary,
@@ -788,6 +803,8 @@ e_book_backend_summary_add_contact (EBookBackendSummary *summary,
  * @id: a unique contact ID string
  *
  * Removes the summary of the contact identified by @id from @summary.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 void
 e_book_backend_summary_remove_contact (EBookBackendSummary *summary,
@@ -819,6 +836,8 @@ e_book_backend_summary_remove_contact (EBookBackendSummary *summary,
  * exists in @summary.
  *
  * Returns: %TRUE if the summary exists, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_summary_check_contact (EBookBackendSummary *summary,
@@ -860,6 +879,8 @@ summary_flush_func (gpointer data)
  * @summary: an #EBookBackendSummary
  *
  * Indicates that @summary has changed and should be flushed to disk.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 void
 e_book_backend_summary_touch (EBookBackendSummary *summary)
@@ -883,6 +904,8 @@ e_book_backend_summary_touch (EBookBackendSummary *summary)
  * Checks if @summary is more recent than @t.
  *
  * Returns: %TRUE if the summary is up to date, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_summary_is_up_to_date (EBookBackendSummary *summary,
@@ -955,6 +978,8 @@ static const struct {
  * stored by @summary.
  *
  * Returns: %TRUE if the query can be satisfied, %FALSE otherwise.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gboolean
 e_book_backend_summary_is_summary_query (EBookBackendSummary *summary,
@@ -1201,6 +1226,8 @@ static const struct {
  * Searches @summary for contacts matching @query.
  *
  * Returns: A #GPtrArray of pointers to contact ID strings.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 GPtrArray *
 e_book_backend_summary_search (EBookBackendSummary *summary,
@@ -1261,6 +1288,8 @@ e_book_backend_summary_search (EBookBackendSummary *summary,
  * by @id.
  *
  * Returns: A new VCard, or %NULL if the contact summary didn't exist.
+ *
+ * Deprecated: 3.12: Use #EBookSqlite instead
  **/
 gchar *
 e_book_backend_summary_get_summary_vcard (EBookBackendSummary *summary,
diff --git a/addressbook/libedata-book/e-book-backend-summary.h 
b/addressbook/libedata-book/e-book-backend-summary.h
index b229d19..285bad2 100644
--- a/addressbook/libedata-book/e-book-backend-summary.h
+++ b/addressbook/libedata-book/e-book-backend-summary.h
@@ -28,6 +28,8 @@
 #ifndef E_BOOK_BACKEND_SUMMARY_H
 #define E_BOOK_BACKEND_SUMMARY_H
 
+#ifndef EDS_DISABLE_DEPRECATED
+
 #include <libebook-contacts/libebook-contacts.h>
 
 /* Standard GObject macros */
@@ -103,4 +105,6 @@ gchar *             e_book_backend_summary_get_summary_vcard
 
 G_END_DECLS
 
+#endif /* EDS_DISABLE_DEPRECATED */
+
 #endif /* E_BOOK_BACKEND_SUMMARY_H */
diff --git a/addressbook/libedata-book/e-book-backend.c b/addressbook/libedata-book/e-book-backend.c
index 36d1726..ddd210d 100644
--- a/addressbook/libedata-book/e-book-backend.c
+++ b/addressbook/libedata-book/e-book-backend.c
@@ -22,6 +22,15 @@
  * Copyright (C) 2012 Intel Corporation
  */
 
+/**
+ * SECTION: e-book-backend
+ * @include: libedata-book/libedata-book.h
+ * @short_description: An abstract class for implementing addressbook backends
+ *
+ * This is the main server facing API for interfacing with addressbook backends,
+ * addressbook backends must implement methods on this class.
+ **/
+
 #include <config.h>
 
 #include <glib/gi18n-lib.h>
diff --git a/addressbook/libedata-book/e-data-book-direct.c b/addressbook/libedata-book/e-data-book-direct.c
index 456095c..7bb9c4e 100644
--- a/addressbook/libedata-book/e-data-book-direct.c
+++ b/addressbook/libedata-book/e-data-book-direct.c
@@ -18,6 +18,20 @@
  * Author: Tristan Van Berkom <tristanvb openismus com>
  */
 
+/**
+ * SECTION: e-data-book-direct
+ * @include: libedata-book/libedata-book.h
+ * @short_description: An interface for implementing Direct Read Access
+ *
+ * This class should be created by an #EBookBackendClass.get_direct_book()
+ * implementation of a backend which supports direct read access.
+ *
+ * This will only be asked of the backend when instantiated on the server
+ * side. If the server side instance of an #EBookBackend does return
+ * an #EDataBookDirect, then a client side instance of the same backend
+ * will be created and #EBookBackendClass.configure_direct() will be
+ * called on the corresponding client side instance.
+ **/
 #ifdef HAVE_CONFIG_H
 #include <config.h>
 #endif
diff --git a/addressbook/libedata-book/e-data-book-factory.c b/addressbook/libedata-book/e-data-book-factory.c
index 3ba7214..ba221d8 100644
--- a/addressbook/libedata-book/e-data-book-factory.c
+++ b/addressbook/libedata-book/e-data-book-factory.c
@@ -20,6 +20,15 @@
  * Author: Ross Burton <ross linux intel com>
  */
 
+/**
+ * SECTION: e-data-book-factory
+ * @include: libedata-book/libedata-book.h
+ * @short_description: The main addressbook server object
+ *
+ * This class handles incomming D-Bus connections and creates
+ * the #EDataBook layer for server side addressbooks to communicate
+ * with client side #EBookClient objects.
+ **/
 #include <config.h>
 #include <locale.h>
 #include <stdlib.h>
diff --git a/addressbook/libedata-book/e-data-book-view.c b/addressbook/libedata-book/e-data-book-view.c
index df4970c..8291dd6 100644
--- a/addressbook/libedata-book/e-data-book-view.c
+++ b/addressbook/libedata-book/e-data-book-view.c
@@ -20,6 +20,18 @@
  * Author: Ross Burton <ross linux intel com>
  */
 
+/**
+ * SECTION: e-data-book-view
+ * @include: libedata-book/libedata-book.h
+ * @short_description: A server side object for issuing view notifications
+ *
+ * This class communicates with #EBookClientViews over the bus.
+ *
+ * Addressbook backends can automatically own a number of views requested
+ * by the client, this API can be used by the backend to issue notifications
+ * which will be delivered to the #EBookClientView
+ **/
+
 #ifdef HAVE_CONFIG_H
 #include <config.h>
 #endif
diff --git a/addressbook/libedata-book/e-data-book.c b/addressbook/libedata-book/e-data-book.c
index 97b04b2..904a40e 100644
--- a/addressbook/libedata-book/e-data-book.c
+++ b/addressbook/libedata-book/e-data-book.c
@@ -16,6 +16,15 @@
  *
  */
 
+/**
+ * SECTION: e-data-book
+ * @include: libedata-book/libedata-book.h
+ * @short_description: Server side D-Bus layer to communicate with addressbooks
+ *
+ * This class communicates with #EBookClients over the bus and accesses
+ * an #EBookBackend to satisfy client requests.
+ **/
+
 #ifdef HAVE_CONFIG_H
 #include <config.h>
 #endif
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]