From 275c0debfd9b1735827ea349af0de3093bea6e64 Mon Sep 17 00:00:00 2001 From: Matthew Barnes Date: Sun, 28 Aug 2011 23:24:07 -0400 Subject: [PATCH] Make sure all new APIs have "Since: 3.2" tags. --- addressbook/libebook/e-book-client.c | 9 + addressbook/libebook/e-book-client.h | 45 +++++ addressbook/libebook/e-contact.c | 16 ++ addressbook/libebook/e-destination.c | 4 + addressbook/libebook/e-vcard.c | 2 + addressbook/libebook/e-vcard.h | 25 +++ .../libedata-book/e-book-backend-sqlitedb.c | 152 +++++++++++++++ .../libedata-book/e-book-backend-sqlitedb.h | 15 ++ addressbook/libedata-book/e-book-backend-sync.c | 2 + addressbook/libedata-book/e-book-backend.c | 22 +++ addressbook/libedata-book/e-book-backend.h | 71 +++++++ addressbook/libedata-book/e-data-book-factory.c | 2 + addressbook/libedata-book/e-data-book-view.c | 2 + addressbook/libedata-book/e-data-book.c | 77 +++++++- calendar/libecal/e-cal-client-view.c | 8 + calendar/libecal/e-cal-client-view.h | 8 + calendar/libecal/e-cal-client.c | 11 ++ calendar/libecal/e-cal-client.h | 52 +++++ calendar/libecal/e-cal-util.h | 9 + calendar/libecal/e-cal.h | 7 + calendar/libedata-cal/e-cal-backend-sync.c | 4 + calendar/libedata-cal/e-cal-backend.c | 38 +++- calendar/libedata-cal/e-cal-backend.h | 71 +++++++ calendar/libedata-cal/e-data-cal-factory.c | 2 + calendar/libedata-cal/e-data-cal-view.c | 8 +- calendar/libedata-cal/e-data-cal.c | 105 ++++++++-- camel/camel-data-cache.c | 2 + camel/camel-enums.h | 11 ++ camel/camel-folder-search.c | 13 +- camel/camel-folder.c | 4 +- camel/camel-junk-filter.c | 66 +++++++ camel/camel-junk-filter.h | 5 + camel/camel-network-service.h | 5 + camel/camel-network-settings.h | 5 + camel/camel-offline-settings.h | 8 + camel/camel-provider.h | 5 + camel/camel-session.c | 2 + camel/camel-settings.h | 8 + camel/camel-store-settings.h | 8 + camel/camel-subscribable.h | 5 + docs/reference/libebackend/libebackend-docs.xml | 5 + .../libedataserver/libedataserver-sections.txt | 1 + .../libedataserver/tmpl/e-operation-pool.sgml | 6 + libebackend/e-sqlite3-vfs.c | 5 + libedataserver/e-client.c | 51 +++-- libedataserver/e-client.h | 87 +++++++++ libedataserver/e-credentials.c | 216 ++++++++++++++++++--- libedataserver/e-credentials.h | 78 ++++++++ libedataserver/e-data-server-util.c | 21 ++ libedataserver/e-data-server-util.h | 11 +- libedataserver/e-operation-pool.c | 51 ++++- libedataserver/e-operation-pool.h | 8 + libedataserverui/e-categories-editor.h | 8 + libedataserverui/e-categories-selector.h | 8 + libedataserverui/e-category-editor.h | 8 + libedataserverui/e-client-utils.c | 32 ++- libedataserverui/e-client-utils.h | 10 + libedataserverui/e-contact-store.c | 8 + 58 files changed, 1443 insertions(+), 85 deletions(-) diff --git a/addressbook/libebook/e-book-client.c b/addressbook/libebook/e-book-client.c index 48bf948..af19914 100644 --- a/addressbook/libebook/e-book-client.c +++ b/addressbook/libebook/e-book-client.c @@ -77,6 +77,13 @@ e_book_client_error_quark (void) return q; } +/** + * e_book_client_error_to_string: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ const gchar * e_book_client_error_to_string (EBookClientError code) { @@ -107,6 +114,8 @@ e_book_client_error_to_string (EBookClientError code) * otherwise the given message is used. * * Returned pointer should be freed with g_error_free(). + * + * Since: 3.2 **/ GError * e_book_client_error_create (EBookClientError code, diff --git a/addressbook/libebook/e-book-client.h b/addressbook/libebook/e-book-client.h index 8c51203..1435ce8 100644 --- a/addressbook/libebook/e-book-client.h +++ b/addressbook/libebook/e-book-client.h @@ -38,14 +38,51 @@ G_BEGIN_DECLS #define E_IS_BOOK_CLIENT_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), E_TYPE_BOOK_CLIENT)) #define E_BOOK_CLIENT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), E_TYPE_BOOK_CLIENT, EBookClientClass)) +/** + * BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS "required-fields" + +/** + * BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS "supported-fields" + +/** + * BOOK_BACKEND_PROPERTY_SUPPORTED_AUTH_METHODS: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define BOOK_BACKEND_PROPERTY_SUPPORTED_AUTH_METHODS "supported-auth-methods" +/** + * E_BOOK_CLIENT_ERROR: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define E_BOOK_CLIENT_ERROR e_book_client_error_quark () GQuark e_book_client_error_quark (void) G_GNUC_CONST; +/** + * EBookClientError: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ typedef enum { E_BOOK_CLIENT_ERROR_NO_SUCH_BOOK, E_BOOK_CLIENT_ERROR_CONTACT_NOT_FOUND, @@ -61,6 +98,14 @@ typedef struct _EBookClient EBookClient; typedef struct _EBookClientClass EBookClientClass; typedef struct _EBookClientPrivate EBookClientPrivate; +/** + * EBookClient: + * + * Contains only private data that should be read and manipulated using the + * functions below. + * + * Since: 3.2 + **/ struct _EBookClient { EClient parent; diff --git a/addressbook/libebook/e-contact.c b/addressbook/libebook/e-contact.c index 5032db2..b9fdf41 100644 --- a/addressbook/libebook/e-contact.c +++ b/addressbook/libebook/e-contact.c @@ -2033,6 +2033,8 @@ e_contact_date_new (void) * Creates a new #EContactPhoto struct. * * Returns: (transfer full): A new #EContactPhoto struct. + * + * Since: 3.2 **/ EContactPhoto * e_contact_photo_new (void) @@ -2108,6 +2110,8 @@ e_contact_photo_copy (EContactPhoto *photo) * * Returns: (transfer none) (array length=len): the inlined image in the * #EContactPhoto. + * + * Since: 3.2 **/ const guchar * e_contact_photo_get_inlined (EContactPhoto *photo, @@ -2127,6 +2131,8 @@ e_contact_photo_get_inlined (EContactPhoto *photo, * @len: the length of @data * * Sets the @photo's inlined data. + * + * Since: 3.2 **/ void e_contact_photo_set_inlined (EContactPhoto *photo, @@ -2148,6 +2154,8 @@ e_contact_photo_set_inlined (EContactPhoto *photo, * Gets the @photo's mime type. * * Returns: (transfer none): the mime type of the image + * + * Since: 3.2 **/ const gchar * e_contact_photo_get_mime_type (EContactPhoto *photo) @@ -2164,6 +2172,8 @@ e_contact_photo_get_mime_type (EContactPhoto *photo) * @mime_type: the mime type * * Sets the @photo's mime type. + * + * Since: 3.2 **/ void e_contact_photo_set_mime_type (EContactPhoto *photo, @@ -2183,6 +2193,8 @@ e_contact_photo_set_mime_type (EContactPhoto *photo, * Gets the @photo's URI. * * Returns: (transfer none): the URI of the image + * + * Since: 3.2 **/ const gchar * e_contact_photo_get_uri (EContactPhoto *photo) @@ -2199,6 +2211,8 @@ e_contact_photo_get_uri (EContactPhoto *photo) * @uri: the @photo's URI * * Sets the @photo's URI. + * + * Since: 3.2 **/ void e_contact_photo_set_uri (EContactPhoto *photo, @@ -2245,6 +2259,8 @@ E_CONTACT_DEFINE_BOXED_TYPE (e_contact_geo, "EContactGeo") * Creates a new #EContactAddress struct. * * Returns: (transfer full): A new #EContactAddress struct. + * + * Since: 3.2 **/ EContactAddress * e_contact_address_new (void) diff --git a/addressbook/libebook/e-destination.c b/addressbook/libebook/e-destination.c index 2110858..9d0253e 100644 --- a/addressbook/libebook/e-destination.c +++ b/addressbook/libebook/e-destination.c @@ -584,6 +584,8 @@ e_destination_set_book (EDestination *dest, * * Specify the source @dest's contact comes from. This is useful * if you need to update the contact later. + * + * Since: 3.2 **/ void e_destination_set_client (EDestination *dest, @@ -1170,6 +1172,8 @@ e_destination_list_show_addresses (const EDestination *dest) * The list and its elements belong to @dest, and should not be freed. * * Returns: (element-type EDestination) (transfer none): A list of elements of type #EDestination, or %NULL. + * + * Since: 3.2 **/ const GList * e_destination_list_get_root_dests (const EDestination *dest) diff --git a/addressbook/libebook/e-vcard.c b/addressbook/libebook/e-vcard.c index 0209ac8..01efbd4 100644 --- a/addressbook/libebook/e-vcard.c +++ b/addressbook/libebook/e-vcard.c @@ -2165,6 +2165,8 @@ e_vcard_attribute_get_param (EVCardAttribute *attr, * Check if the @evc has been parsed already. Used for debugging. * * Return value: %TRUE if @evc has been parsed, %FALSE otherwise. + * + * Since: 3.2 **/ gboolean e_vcard_is_parsed (EVCard *evc) diff --git a/addressbook/libebook/e-vcard.h b/addressbook/libebook/e-vcard.h index 31d6000..e03b881 100644 --- a/addressbook/libebook/e-vcard.h +++ b/addressbook/libebook/e-vcard.h @@ -84,7 +84,14 @@ G_BEGIN_DECLS #define EVC_X_JABBER "X-JABBER" #define EVC_X_LIST_SHOW_ADDRESSES "X-EVOLUTION-LIST-SHOW-ADDRESSES" #define EVC_X_LIST "X-EVOLUTION-LIST" + +/** + * EVC_X_LIST_NAME: + * + * Since: 3.2 + **/ #define EVC_X_LIST_NAME "X-EVOLUTION-LIST-NAME" + #define EVC_X_MANAGER "X-EVOLUTION-MANAGER" #define EVC_X_MSN "X-MSN" #define EVC_X_RADIO "X-EVOLUTION-RADIO" @@ -119,8 +126,26 @@ G_BEGIN_DECLS #define EVC_X_BOOK_URI "X-EVOLUTION-BOOK-URI" /* Constants for Evo contact lists only */ + +/** + * EVC_CONTACT_LIST + * + * Since: 3.2 + **/ #define EVC_CONTACT_LIST "X-EVOLUTION-CONTACT-LIST-INFO" + +/** + * EVC_PARENT_CL: + * + * Since: 3.2 + **/ #define EVC_PARENT_CL "X-EVOLUTION-PARENT-UID" + +/** + * EVC_CL_UID: + * + * Since: 3.2 + **/ #define EVC_CL_UID "X-EVOLUTION-CONTACT-LIST-UID" #ifndef EDS_DISABLE_DEPRECATED diff --git a/addressbook/libedata-book/e-book-backend-sqlitedb.c b/addressbook/libedata-book/e-book-backend-sqlitedb.c index 26e6284..80184ba 100644 --- a/addressbook/libedata-book/e-book-backend-sqlitedb.c +++ b/addressbook/libedata-book/e-book-backend-sqlitedb.c @@ -507,6 +507,8 @@ book_backend_sqlitedb_load (EBookBackendSqliteDB *ebsdb, * would be stored in same db in different tables. * * Returns: + * + * Since: 3.2 **/ EBookBackendSqliteDB * e_book_backend_sqlitedb_new (const gchar *path, @@ -630,6 +632,8 @@ insert_stmt_from_contact (EContact *contact, * which is the preferred means to add multiple contacts when possible. * * Returns: TRUE on success. + * + * Since: 3.2 **/ gboolean e_book_backend_sqlitedb_add_contact (EBookBackendSqliteDB *ebsdb, @@ -656,6 +660,8 @@ e_book_backend_sqlitedb_add_contact (EBookBackendSqliteDB *ebsdb, * * * Returns: TRUE on success. + * + * Since: 3.2 **/ gboolean e_book_backend_sqlitedb_add_contacts (EBookBackendSqliteDB *ebsdb, @@ -695,6 +701,13 @@ e_book_backend_sqlitedb_add_contacts (EBookBackendSqliteDB *ebsdb, return ret && !err; } +/** + * e_book_backend_sqlitedb_remove_contact: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ gboolean e_book_backend_sqlitedb_remove_contact (EBookBackendSqliteDB *ebsdb, const gchar *folderid, @@ -708,6 +721,13 @@ e_book_backend_sqlitedb_remove_contact (EBookBackendSqliteDB *ebsdb, error); } +/** + * e_book_backend_sqlitedb_remove_contacts: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ gboolean e_book_backend_sqlitedb_remove_contacts (EBookBackendSqliteDB *ebsdb, const gchar *folderid, @@ -777,6 +797,13 @@ contact_found_cb (gpointer ref, return 0; } +/** + * e_book_backend_sqlitedb_has_contact: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ gboolean e_book_backend_sqlitedb_has_contact (EBookBackendSqliteDB *ebsdb, const gchar *folderid, @@ -821,6 +848,13 @@ get_vcard_cb (gpointer ref, return 0; } +/** + * e_book_backend_sqlitedb_get_contact: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ EContact * e_book_backend_sqlitedb_get_contact (EBookBackendSqliteDB *ebsdb, const gchar *folderid, @@ -877,6 +911,13 @@ check_field_foreach (const gchar *field_name, } } +/** + * e_book_backend_sqlitedb_is_summary_fields: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ gboolean e_book_backend_sqlitedb_is_summary_fields (GHashTable *fields_of_interest) { @@ -943,6 +984,8 @@ summary_select_stmt (const gchar *folderid, * the returned vcard string satisfies the passed 'fields_of_interest' parameter. * * Returns: (transfer full): The vcard string for @uid or %NULL if @uid was not found. + * + * Since: 3.2 */ gchar * e_book_backend_sqlitedb_get_vcard_string (EBookBackendSqliteDB *ebsdb, @@ -1044,6 +1087,13 @@ static const struct { { "exists", func_check, 0 } }; +/** + * e_book_backend_sqlitedb_is_summary_query: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ gboolean e_book_backend_sqlitedb_is_summary_query (const gchar *query) { @@ -1494,6 +1544,8 @@ book_backend_sqlitedb_search_full (EBookBackendSqliteDB *ebsdb, * and fetch for full required data from another persistance. * * Returns: List of EbSdbSearchData. + * + * Since: 3.2 **/ GSList * e_book_backend_sqlitedb_search (EBookBackendSqliteDB *ebsdb, @@ -1539,6 +1591,13 @@ e_book_backend_sqlitedb_search (EBookBackendSqliteDB *ebsdb, return search_contacts; } +/** + * e_book_backend_sqlitedb_search_uids: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ GSList * e_book_backend_sqlitedb_search_uids (EBookBackendSqliteDB *ebsdb, const gchar *folderid, @@ -1595,6 +1654,13 @@ get_bool_cb (gpointer ref, return 0; } +/** + * e_book_backend_sqlitedb_get_is_populated: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ gboolean e_book_backend_sqlitedb_get_is_populated (EBookBackendSqliteDB *ebsdb, const gchar *folderid, @@ -1615,6 +1681,13 @@ e_book_backend_sqlitedb_get_is_populated (EBookBackendSqliteDB *ebsdb, } +/** + * e_book_backend_sqlitedb_set_is_populated: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ gboolean e_book_backend_sqlitedb_set_is_populated (EBookBackendSqliteDB *ebsdb, const gchar *folderid, @@ -1652,6 +1725,8 @@ e_book_backend_sqlitedb_set_is_populated (EBookBackendSqliteDB *ebsdb, * * Returns: TRUE if the vcards stored in the db were downloaded partially. It is to indicate * the stored vcards does not contain the full data. + * + * Since: 3.2 **/ gboolean e_book_backend_sqlitedb_get_has_partial_content (EBookBackendSqliteDB *ebsdb, @@ -1672,6 +1747,13 @@ e_book_backend_sqlitedb_get_has_partial_content (EBookBackendSqliteDB *ebsdb, return ret; } +/** + * e_book_backend_sqlitedb_set_has_partial_content: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ gboolean e_book_backend_sqlitedb_set_has_partial_content (EBookBackendSqliteDB *ebsdb, const gchar *folderid, @@ -1713,6 +1795,13 @@ get_string_cb (gpointer ref, return 0; } +/** + * e_book_backend_sqlitedb_get_contact_bdata: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ gchar * e_book_backend_sqlitedb_get_contact_bdata (EBookBackendSqliteDB *ebsdb, const gchar *folderid, @@ -1732,6 +1821,13 @@ e_book_backend_sqlitedb_get_contact_bdata (EBookBackendSqliteDB *ebsdb, return ret; } +/** + * e_book_backend_sqlitedb_set_contact_bdata: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ gboolean e_book_backend_sqlitedb_set_contact_bdata (EBookBackendSqliteDB *ebsdb, const gchar *folderid, @@ -1761,6 +1857,13 @@ e_book_backend_sqlitedb_set_contact_bdata (EBookBackendSqliteDB *ebsdb, return !err; } +/** + * e_book_backend_sqlitedb_get_sync_data: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ gchar * e_book_backend_sqlitedb_get_sync_data (EBookBackendSqliteDB *ebsdb, const gchar *folderid, @@ -1779,6 +1882,13 @@ e_book_backend_sqlitedb_get_sync_data (EBookBackendSqliteDB *ebsdb, return ret; } +/** + * e_book_backend_sqlitedb_set_sync_data: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ gboolean e_book_backend_sqlitedb_set_sync_data (EBookBackendSqliteDB *ebsdb, const gchar *folderid, @@ -1807,6 +1917,13 @@ e_book_backend_sqlitedb_set_sync_data (EBookBackendSqliteDB *ebsdb, return !err; } +/** + * e_book_backend_sqlitedb_get_key_value: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ gchar * e_book_backend_sqlitedb_get_key_value (EBookBackendSqliteDB *ebsdb, const gchar *folderid, @@ -1827,6 +1944,13 @@ e_book_backend_sqlitedb_get_key_value (EBookBackendSqliteDB *ebsdb, return ret; } +/** + * e_book_backend_sqlitedb_set_key_value: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ gboolean e_book_backend_sqlitedb_set_key_value (EBookBackendSqliteDB *ebsdb, const gchar *folderid, @@ -1856,6 +1980,13 @@ e_book_backend_sqlitedb_set_key_value (EBookBackendSqliteDB *ebsdb, return !err; } +/** + * e_book_backend_sqlitedb_get_partially_cached_ids: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ GSList * e_book_backend_sqlitedb_get_partially_cached_ids (EBookBackendSqliteDB *ebsdb, const gchar *folderid, @@ -1876,6 +2007,13 @@ e_book_backend_sqlitedb_get_partially_cached_ids (EBookBackendSqliteDB *ebsdb, return uids; } +/** + * e_book_backend_sqlitedb_delete_addressbook: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ gboolean e_book_backend_sqlitedb_delete_addressbook (EBookBackendSqliteDB *ebsdb, const gchar *folderid, @@ -1917,6 +2055,13 @@ e_book_backend_sqlitedb_delete_addressbook (EBookBackendSqliteDB *ebsdb, return !err; } +/** + * e_book_backend_sqlitedb_search_data_free: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ void e_book_backend_sqlitedb_search_data_free (EbSdbSearchData *s_data) { @@ -1928,6 +2073,13 @@ e_book_backend_sqlitedb_search_data_free (EbSdbSearchData *s_data) } } +/** + * e_book_backend_sqlitedb_remove: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ gboolean e_book_backend_sqlitedb_remove (EBookBackendSqliteDB *ebsdb, GError **error) diff --git a/addressbook/libedata-book/e-book-backend-sqlitedb.h b/addressbook/libedata-book/e-book-backend-sqlitedb.h index b51e2cd..e418523 100644 --- a/addressbook/libedata-book/e-book-backend-sqlitedb.h +++ b/addressbook/libedata-book/e-book-backend-sqlitedb.h @@ -51,6 +51,14 @@ typedef struct _EBookBackendSqliteDB EBookBackendSqliteDB; typedef struct _EBookBackendSqliteDBClass EBookBackendSqliteDBClass; typedef struct _EBookBackendSqliteDBPrivate EBookBackendSqliteDBPrivate; +/** + * EBookBackendSqliteDB: + * + * Contains only private data that should be read and manipulated using the + * functions below. + * + * Since: 3.2 + **/ struct _EBookBackendSqliteDB { GObject parent; EBookBackendSqliteDBPrivate *priv; @@ -62,6 +70,13 @@ struct _EBookBackendSqliteDBClass { /* virtual methods */ }; +/** + * EbSdbSearchData: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ typedef struct { gchar *vcard; gchar *uid; diff --git a/addressbook/libedata-book/e-book-backend-sync.c b/addressbook/libedata-book/e-book-backend-sync.c index c4c42e2..8c39269 100644 --- a/addressbook/libedata-book/e-book-backend-sync.c +++ b/addressbook/libedata-book/e-book-backend-sync.c @@ -43,6 +43,8 @@ e_book_backend_sync_construct (EBookBackendSync *backend) * @error: #GError to set, when something fails * * Opens @backend, which can involve connecting it to a remote server. + * + * Since: 3.2 **/ void e_book_backend_sync_open (EBookBackendSync *backend, diff --git a/addressbook/libedata-book/e-book-backend.c b/addressbook/libedata-book/e-book-backend.c index ef8f78a..f014849 100644 --- a/addressbook/libedata-book/e-book-backend.c +++ b/addressbook/libedata-book/e-book-backend.c @@ -848,6 +848,8 @@ e_book_backend_remove_client (EBookBackend *backend, * * Calls @callback for each known book view of this @backend. * @callback returns %FALSE to stop further processing. + * + * Since: 3.2 **/ void e_book_backend_foreach_view (EBookBackend *backend, @@ -946,6 +948,8 @@ e_book_backend_set_backend_property (EBookBackend *backend, * Checks if @backend's storage is online. * * Returns: %TRUE if online, %FALSE otherwise. + * + * Since: 3.2 **/ gboolean e_book_backend_is_online (EBookBackend *backend) @@ -965,6 +969,8 @@ e_book_backend_is_online (EBookBackend *backend) * within call of e_book_backend_notify_opened(). * * Returns: %TRUE if fully opened, %FALSE otherwise. + * + * Since: 3.2 **/ gboolean e_book_backend_is_opened (EBookBackend *backend) @@ -986,6 +992,8 @@ e_book_backend_is_opened (EBookBackend *backend) * it is being opening. * * Returns: %TRUE if opening phase is in the effect, %FALSE otherwise. + * + * Since: 3.2 **/ gboolean e_book_backend_is_opening (EBookBackend *backend) @@ -1002,6 +1010,8 @@ e_book_backend_is_opening (EBookBackend *backend) * Checks if we can write to @backend. * * Returns: %TRUE if writeable, %FALSE if not. + * + * Since: 3.2 **/ gboolean e_book_backend_is_readonly (EBookBackend *backend) @@ -1163,6 +1173,8 @@ e_book_backend_notify_complete (EBookBackend *backend) * Notifies each backend listener about an error. This is meant to be used * for cases where is no GError return possibility, to notify user about * an issue. + * + * Since: 3.2 **/ void e_book_backend_notify_error (EBookBackend *backend, @@ -1187,6 +1199,8 @@ e_book_backend_notify_error (EBookBackend *backend, * @is_readonly: flag indicating readonly status * * Notifies all backend's clients about the current readonly state. + * + * Since: 3.2 **/ void e_book_backend_notify_readonly (EBookBackend *backend, @@ -1213,6 +1227,8 @@ e_book_backend_notify_readonly (EBookBackend *backend, * * Notifies clients of @backend's connection status indicated by @is_online. * Meant to be used by backend implementations. + * + * Since: 3.2 **/ void e_book_backend_notify_online (EBookBackend *backend, @@ -1291,6 +1307,8 @@ e_book_backend_notify_auth_required (EBookBackend *backend, * Note: The @error is freed automatically if not %NULL. * * Meant to be used by backend implementations. + * + * Since: 3.2 **/ void e_book_backend_notify_opened (EBookBackend *backend, @@ -1321,6 +1339,8 @@ e_book_backend_notify_opened (EBookBackend *backend, * @prop_value: new property value * * Notifies clients about property value change. + * + * Since: 3.2 **/ void e_book_backend_notify_property_changed (EBookBackend *backend, @@ -1359,6 +1379,8 @@ e_book_backend_notify_property_changed (EBookBackend *backend, * and e_data_book_respond_open() with the same @error. * * See e_book_backend_open() for more details how the opening phase works. + * + * Since: 3.2 **/ void e_book_backend_respond_opened (EBookBackend *backend, diff --git a/addressbook/libedata-book/e-book-backend.h b/addressbook/libedata-book/e-book-backend.h index dbb35e6..b301830 100644 --- a/addressbook/libedata-book/e-book-backend.h +++ b/addressbook/libedata-book/e-book-backend.h @@ -39,14 +39,85 @@ G_BEGIN_DECLS #define E_IS_BOOK_BACKEND_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), E_TYPE_BOOK_BACKEND)) #define E_BOOK_BACKEND_GET_CLASS(k) (G_TYPE_INSTANCE_GET_CLASS ((k), E_TYPE_BOOK_BACKEND, EBookBackendClass)) +/** + * CLIENT_BACKEND_PROPERTY_OPENED: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define CLIENT_BACKEND_PROPERTY_OPENED "opened" + +/** + * CLIENT_BACKEND_PROPERTY_OPENING: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define CLIENT_BACKEND_PROPERTY_OPENING "opening" + +/** + * CLIENT_BACKEND_PROPERTY_ONLINE: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define CLIENT_BACKEND_PROPERTY_ONLINE "online" + +/** + * CLIENT_BACKEND_PROPERTY_READONLY: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define CLIENT_BACKEND_PROPERTY_READONLY "readonly" + +/** + * CLIENT_BACKEND_PROPERTY_CACHE_DIR: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define CLIENT_BACKEND_PROPERTY_CACHE_DIR "cache-dir" + +/** + * CLIENT_BACKEND_PROPERTY_CAPABILITIES: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define CLIENT_BACKEND_PROPERTY_CAPABILITIES "capabilities" + +/** + * BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS "required-fields" + +/** + * BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS "supported-fields" + +/** + * BOOK_BACKEND_PROPERTY_SUPPORTED_AUTH_METHODS: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define BOOK_BACKEND_PROPERTY_SUPPORTED_AUTH_METHODS "supported-auth-methods" typedef struct _EBookBackendPrivate EBookBackendPrivate; diff --git a/addressbook/libedata-book/e-data-book-factory.c b/addressbook/libedata-book/e-data-book-factory.c index be904c5..4063929 100644 --- a/addressbook/libedata-book/e-data-book-factory.c +++ b/addressbook/libedata-book/e-data-book-factory.c @@ -195,6 +195,8 @@ e_data_book_factory_register_backends (EDataBookFactory *book_factory) * @is_online: Online mode to set. * * Sets the online mode for all backends created by the given factory. + * + * Since: 3.2 */ void e_data_book_factory_set_backend_online (EDataBookFactory *factory, diff --git a/addressbook/libedata-book/e-data-book-view.c b/addressbook/libedata-book/e-data-book-view.c index 1aa51f8..68008e6 100644 --- a/addressbook/libedata-book/e-data-book-view.c +++ b/addressbook/libedata-book/e-data-book-view.c @@ -574,6 +574,8 @@ e_data_book_view_notify_complete (EDataBookView *book_view, * Provides listeners with a human-readable text describing the * current backend operation. This can be used for progress * reporting. + * + * Since: 3.2 **/ void e_data_book_view_notify_progress (EDataBookView *book_view, diff --git a/addressbook/libedata-book/e-data-book.c b/addressbook/libedata-book/e-data-book.c index dc8b1bf..89689ab 100644 --- a/addressbook/libedata-book/e-data-book.c +++ b/addressbook/libedata-book/e-data-book.c @@ -460,8 +460,14 @@ data_book_return_error (GDBusMethodInvocation *invocation, g_error_free (error); } -/* takes a list of strings and converts it to a comma-separated string of values; - * free returned pointer with g_free () */ +/** + * e_data_book_string_slist_to_comma_string: + * + * Takes a list of strings and converts it to a comma-separated string of + * values; free returned pointer with g_free() + * + * Since: 3.2 + **/ gchar * e_data_book_string_slist_to_comma_string (const GSList *strings) { @@ -883,6 +889,13 @@ e_data_book_respond_refresh (EDataBook *book, g_error_free (error); } +/** + * e_data_book_respond_get_backend_property: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ void e_data_book_respond_get_backend_property (EDataBook *book, guint32 opid, @@ -904,6 +917,13 @@ e_data_book_respond_get_backend_property (EDataBook *book, g_free (gdbus_prop_value); } +/** + * e_data_book_respond_set_backend_property: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ void e_data_book_respond_set_backend_property (EDataBook *book, guint32 opid, @@ -968,6 +988,13 @@ e_data_book_respond_get_contact_list (EDataBook *book, } } +/** + * e_data_book_respond_get_contact_list_uids: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ void e_data_book_respond_get_contact_list_uids (EDataBook *book, guint32 opid, @@ -1066,6 +1093,13 @@ e_data_book_respond_remove_contacts (EDataBook *book, } +/** + * e_data_book_report_error: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ void e_data_book_report_error (EDataBook *book, const gchar *message) @@ -1076,6 +1110,13 @@ e_data_book_report_error (EDataBook *book, e_gdbus_book_emit_backend_error (book->priv->gdbus_object, message); } +/** + * e_data_book_report_readonly: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ void e_data_book_report_readonly (EDataBook *book, gboolean readonly) @@ -1085,6 +1126,13 @@ e_data_book_report_readonly (EDataBook *book, e_gdbus_book_emit_readonly (book->priv->gdbus_object, readonly); } +/** + * e_data_book_report_online: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ void e_data_book_report_online (EDataBook *book, gboolean is_online) @@ -1117,11 +1165,16 @@ e_data_book_report_auth_required (EDataBook *book, g_strfreev (strv); } -/* Reports to associated client that opening phase of the book is finished. - * error being NULL means successfully, otherwise reports an error which happened - * during opening phase. By opening phase is meant a process including successfull - * authentication to the server/storage. - */ +/** + * e_data_book_report_opened: + * + * Reports to associated client that opening phase of the book is finished. + * error being NULL means successfully, otherwise reports an error which + * happened during opening phase. By opening phase is meant a process + * including successfull authentication to the server/storage. + * + * Since: 3.2 + **/ void e_data_book_report_opened (EDataBook *book, const GError *error) @@ -1135,7 +1188,13 @@ e_data_book_report_opened (EDataBook *book, g_strfreev (strv_error); } -/* Notifies client about certain property value change */ +/** + * e_data_book_report_backend_property_changed: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ void e_data_book_report_backend_property_changed (EDataBook *book, const gchar *prop_name, @@ -1143,6 +1202,8 @@ e_data_book_report_backend_property_changed (EDataBook *book, { gchar **strv; + /* Notifies client about certain property value change */ + g_return_if_fail (book != NULL); g_return_if_fail (prop_name != NULL); g_return_if_fail (*prop_name != '\0'); diff --git a/calendar/libecal/e-cal-client-view.c b/calendar/libecal/e-cal-client-view.c index 0de0edf..ef330a7 100644 --- a/calendar/libecal/e-cal-client-view.c +++ b/calendar/libecal/e-cal-client-view.c @@ -431,6 +431,8 @@ _e_cal_client_view_new (ECalClient *client, * Get the #ECalClient associated with this view. * * Returns: the associated client. + * + * Since: 3.2 **/ ECalClient * e_cal_client_view_get_client (ECalClientView *view) @@ -446,6 +448,8 @@ e_cal_client_view_get_client (ECalClientView *view) * * Retunrs: Whether view is running. Not running views are ignoring * all events sent from the server. + * + * Since: 3.2 **/ gboolean e_cal_client_view_is_running (ECalClientView *view) @@ -461,6 +465,8 @@ e_cal_client_view_is_running (ECalClientView *view) * @error: A #Gerror * * Starts a live query to the calendar/tasks backend. + * + * Since: 3.2 **/ void e_cal_client_view_start (ECalClientView *view, @@ -493,6 +499,8 @@ e_cal_client_view_start (ECalClientView *view, * @error: A #GError * * Stops a live query to the calendar/tasks backend. + * + * Since: 3.2 */ void e_cal_client_view_stop (ECalClientView *view, diff --git a/calendar/libecal/e-cal-client-view.h b/calendar/libecal/e-cal-client-view.h index d6dd05c..019550b 100644 --- a/calendar/libecal/e-cal-client-view.h +++ b/calendar/libecal/e-cal-client-view.h @@ -37,6 +37,14 @@ typedef struct _ECalClientViewPrivate ECalClientViewPrivate; struct _ECalClient; +/** + * ECalClientView: + * + * Contains only private data that should be read and manipulated using the + * functions below. + * + * Since: 3.2 + **/ struct _ECalClientView { GObject object; diff --git a/calendar/libecal/e-cal-client.c b/calendar/libecal/e-cal-client.c index 9f5aa91..2664221 100644 --- a/calendar/libecal/e-cal-client.c +++ b/calendar/libecal/e-cal-client.c @@ -119,6 +119,13 @@ e_cal_client_error_quark (void) return q; } +/** + * e_cal_client_error_to_string: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ const gchar * e_cal_client_error_to_string (ECalClientError code) { @@ -151,6 +158,8 @@ e_cal_client_error_to_string (ECalClientError code) * otherwise the given message is used. * * Returned pointer should be freed with g_error_free(). + * + * Since: 3.2 **/ GError * e_cal_client_error_create (ECalClientError code, @@ -1198,6 +1207,8 @@ e_cal_client_free_ecalcomp_slist (GSList *ecalcomps) * * Returns: The timezone identified by the @tzid argument, or %NULL if * it could not be found. + * + * Since: 3.2 */ icaltimezone * e_cal_client_resolve_tzid_cb (const gchar *tzid, diff --git a/calendar/libecal/e-cal-client.h b/calendar/libecal/e-cal-client.h index d2cfbab..3e77baf 100644 --- a/calendar/libecal/e-cal-client.h +++ b/calendar/libecal/e-cal-client.h @@ -38,10 +38,40 @@ G_BEGIN_DECLS #define E_IS_CAL_CLIENT_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), E_TYPE_CAL_CLIENT)) #define E_CAL_CLIENT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), E_TYPE_CAL_CLIENT, ECalClientClass)) +/** + * CAL_BACKEND_PROPERTY_CAL_EMAIL_ADDRESS: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define CAL_BACKEND_PROPERTY_CAL_EMAIL_ADDRESS "cal-email-address" + +/** + * CAL_BACKEND_PROPERTY_ALARM_EMAIL_ADDRESS: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define CAL_BACKEND_PROPERTY_ALARM_EMAIL_ADDRESS "alarm-email-address" + +/** + * CAL_BACKEND_PROPERTY_DEFAULT_OBJECT: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define CAL_BACKEND_PROPERTY_DEFAULT_OBJECT "default-object" +/** + * ECalClientSourceType: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ typedef enum { E_CAL_CLIENT_SOURCE_TYPE_EVENTS, E_CAL_CLIENT_SOURCE_TYPE_TASKS, @@ -54,10 +84,24 @@ typedef enum { GType e_cal_client_source_type_enum_get_type (void); +/** + * E_CAL_CLIENT_ERROR: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define E_CAL_CLIENT_ERROR e_cal_client_error_quark () GQuark e_cal_client_error_quark (void) G_GNUC_CONST; +/** + * ECalClientError: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ typedef enum { E_CAL_CLIENT_ERROR_NO_SUCH_CALENDAR, E_CAL_CLIENT_ERROR_OBJECT_NOT_FOUND, @@ -74,6 +118,14 @@ typedef struct _ECalClient ECalClient; typedef struct _ECalClientClass ECalClientClass; typedef struct _ECalClientPrivate ECalClientPrivate; +/** + * ECalClient: + * + * Contains only private data that should be read and manipulated using the + * functions below. + * + * Since: 3.2 + **/ struct _ECalClient { EClient parent; diff --git a/calendar/libecal/e-cal-util.h b/calendar/libecal/e-cal-util.h index 4a69b47..fe6a48d 100644 --- a/calendar/libecal/e-cal-util.h +++ b/calendar/libecal/e-cal-util.h @@ -111,7 +111,16 @@ gboolean e_cal_util_event_dates_match (icalcomponent *icalcomp1, icalcomponent * #define CAL_STATIC_CAPABILITY_NO_THISANDFUTURE "no-thisandfuture" #define CAL_STATIC_CAPABILITY_NO_THISANDPRIOR "no-thisandprior" #define CAL_STATIC_CAPABILITY_NO_TRANSPARENCY "no-transparency" + +/** + * CAL_STATIC_CAPABILITY_REMOVE_ONLY_THIS: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define CAL_STATIC_CAPABILITY_REMOVE_ONLY_THIS "remove-only-this" + #define CAL_STATIC_CAPABILITY_ONE_ALARM_ONLY "one-alarm-only" #define CAL_STATIC_CAPABILITY_ORGANIZER_MUST_ATTEND "organizer-must-attend" #define CAL_STATIC_CAPABILITY_ORGANIZER_NOT_EMAIL_ADDRESS "organizer-not-email-address" diff --git a/calendar/libecal/e-cal.h b/calendar/libecal/e-cal.h index 3374240..3f68394 100644 --- a/calendar/libecal/e-cal.h +++ b/calendar/libecal/e-cal.h @@ -71,6 +71,13 @@ typedef enum { E_CAL_LOAD_LOADED } ECalLoadState; +/** + * EDataCalMode: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ typedef enum { Local = 1 << 0, Remote = 1 << 1, diff --git a/calendar/libedata-cal/e-cal-backend-sync.c b/calendar/libedata-cal/e-cal-backend-sync.c index bdeee2a..27a9c18 100644 --- a/calendar/libedata-cal/e-cal-backend-sync.c +++ b/calendar/libedata-cal/e-cal-backend-sync.c @@ -91,6 +91,8 @@ e_cal_backend_sync_open (ECalBackendSync *backend, * @error: #GError to set, when something fails * * Authenticates @backend with given @credentials. + * + * Since: 3.2 **/ void e_cal_backend_sync_authenticate_user (ECalBackendSync *backend, @@ -454,6 +456,8 @@ e_cal_backend_sync_send_objects (ECalBackendSync *backend, * @error: Out parameter for a #GError. * * Calls the get_attachment_uris_sync method on the given backend. + * + * Since: 3.2 */ void e_cal_backend_sync_get_attachment_uris (ECalBackendSync *backend, diff --git a/calendar/libedata-cal/e-cal-backend.c b/calendar/libedata-cal/e-cal-backend.c index a137e12..b21f085 100644 --- a/calendar/libedata-cal/e-cal-backend.c +++ b/calendar/libedata-cal/e-cal-backend.c @@ -470,6 +470,8 @@ e_cal_backend_get_kind (ECalBackend *backend) * @backend: an #ECalBackend * * Returns: Whether is backend online. + * + * Since: 3.2 **/ gboolean e_cal_backend_is_online (ECalBackend *backend) @@ -489,6 +491,8 @@ e_cal_backend_is_online (ECalBackend *backend) * within call of e_cal_backend_notify_opened(). * * Returns: %TRUE if fully opened, %FALSE otherwise. + * + * Since: 3.2 **/ gboolean e_cal_backend_is_opened (ECalBackend *backend) @@ -499,7 +503,7 @@ e_cal_backend_is_opened (ECalBackend *backend) } /** - * e_cal_backend_is_opening:: + * e_cal_backend_is_opening: * @backend: an #ECalBackend * * Checks if @backend is processing its opening phase, which @@ -510,6 +514,8 @@ e_cal_backend_is_opened (ECalBackend *backend) * it is being opening. * * Returns: %TRUE if opening phase is in the effect, %FALSE otherwise. + * + * Since: 3.2 **/ gboolean e_cal_backend_is_opening (ECalBackend *backend) @@ -525,6 +531,8 @@ e_cal_backend_is_opening (ECalBackend *backend) * * Returns: Whether is backend read-only. This value is the last used * in a call of e_cal_backend_notify_readonly(). + * + * Since: 3.2 **/ gboolean e_cal_backend_is_readonly (ECalBackend *backend) @@ -541,6 +549,8 @@ e_cal_backend_is_readonly (ECalBackend *backend) * Checks if @backend has been removed from its physical storage. * * Returns: %TRUE if @backend has been removed, %FALSE otherwise. + * + * Since: 3.2 **/ gboolean e_cal_backend_is_removed (ECalBackend *backend) @@ -557,6 +567,8 @@ e_cal_backend_is_removed (ECalBackend *backend) * * Sets the flag indicating whether @backend was removed to @is_removed. * Meant to be used by backend implementations. + * + * Since: 3.2 **/ void e_cal_backend_set_is_removed (ECalBackend *backend, @@ -769,6 +781,8 @@ e_cal_backend_remove_client (ECalBackend *backend, * Adds a view to the list of live views being run by the given backend. * Doing so means that any listener on the view will get notified of any * change that affect the live view. + * + * Since: 3.2 */ void e_cal_backend_add_view (ECalBackend *backend, @@ -791,7 +805,7 @@ e_cal_backend_add_view (ECalBackend *backend, * * Removes view from the list of live views for the backend. * - * Since: 2.24 + * Since: 3.2 **/ void e_cal_backend_remove_view (ECalBackend *backend, @@ -815,6 +829,8 @@ e_cal_backend_remove_view (ECalBackend *backend, * * Calls @callback for each known calendar view of this @backend. * @callback returns %FALSE to stop further processing. + * + * Since: 3.2 **/ void e_cal_backend_foreach_view (ECalBackend *backend, @@ -848,6 +864,8 @@ e_cal_backend_foreach_view (ECalBackend *backend, * @proxy: The calendar backend to act as notification proxy. * * Sets the backend that will act as notification proxy for the given backend. + * + * Since: 3.2 */ void e_cal_backend_set_notification_proxy (ECalBackend *backend, @@ -864,6 +882,8 @@ e_cal_backend_set_notification_proxy (ECalBackend *backend, * @is_online: Whether is online * * Sets the online mode of the calendar + * + * Since: 3.2 */ void e_cal_backend_set_online (ECalBackend *backend, @@ -979,6 +999,8 @@ e_cal_backend_open (ECalBackend *backend, * * See information at e_cal_backend_open() for more details * how the opening phase works. + * + * Since: 3.2 **/ void e_cal_backend_authenticate_user (ECalBackend *backend, @@ -1333,6 +1355,8 @@ e_cal_backend_send_objects (ECalBackend *backend, * Queries a calendar backend for attachments present in a calendar object based * on its unique identifier and its recurrence ID (if a recurrent appointment). * This might be finished with e_data_cal_respond_get_attachment_uris(). + * + * Since: 3.2 **/ void e_cal_backend_get_attachment_uris (ECalBackend *backend, @@ -1480,6 +1504,8 @@ e_cal_backend_internal_get_timezone (ECalBackend *backend, * @view: The view to be started. * * Starts a new live view on the given backend. + * + * Since: 3.2 */ void e_cal_backend_start_view (ECalBackend *backend, @@ -1796,6 +1822,8 @@ e_cal_backend_notify_readonly (ECalBackend *backend, * * Notifies clients of @backend's connection status indicated by @is_online. * Meant to be used by backend implementations. + * + * Since: 3.2 **/ void e_cal_backend_notify_online (ECalBackend *backend, @@ -1886,6 +1914,8 @@ e_cal_backend_notify_auth_required (ECalBackend *backend, * Note: The @error is freed automatically if not %NULL. * * Meant to be used by backend implementations. + * + * Since: 3.2 **/ void e_cal_backend_notify_opened (ECalBackend *backend, @@ -1916,6 +1946,8 @@ e_cal_backend_notify_opened (ECalBackend *backend, * @prop_value: new property value * * Notifies client about property value change. + * + * Since: 3.2 **/ void e_cal_backend_notify_property_changed (ECalBackend *backend, @@ -1954,6 +1986,8 @@ e_cal_backend_notify_property_changed (ECalBackend *backend, * e_data_cal_respond_open() with the same @error. * * See e_cal_backend_open() for more details how the opening phase works. + * + * Since: 3.2 **/ void e_cal_backend_respond_opened (ECalBackend *backend, diff --git a/calendar/libedata-cal/e-cal-backend.h b/calendar/libedata-cal/e-cal-backend.h index 840b092..75721f6 100644 --- a/calendar/libedata-cal/e-cal-backend.h +++ b/calendar/libedata-cal/e-cal-backend.h @@ -43,14 +43,85 @@ G_BEGIN_DECLS #define E_IS_CAL_BACKEND_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), E_TYPE_CAL_BACKEND)) #define E_CAL_BACKEND_GET_CLASS(obj) (E_CAL_BACKEND_CLASS (G_OBJECT_GET_CLASS (obj))) +/** + * CLIENT_BACKEND_PROPERTY_OPENED: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define CLIENT_BACKEND_PROPERTY_OPENED "opened" + +/** + * CLIENT_BACKEND_PROPERTY_OPENING: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define CLIENT_BACKEND_PROPERTY_OPENING "opening" + +/** + * CLIENT_BACKEND_PROPERTY_ONLINE: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define CLIENT_BACKEND_PROPERTY_ONLINE "online" + +/** + * CLIENT_BACKEND_PROPERTY_READONLY: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define CLIENT_BACKEND_PROPERTY_READONLY "readonly" + +/** + * CLIENT_BACKEND_PROPERTY_CACHE_DIR: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define CLIENT_BACKEND_PROPERTY_CACHE_DIR "cache-dir" + +/** + * CLIENT_BACKEND_PROPERTY_CAPABILITIES: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define CLIENT_BACKEND_PROPERTY_CAPABILITIES "capabilities" + +/** + * CAL_BACKEND_PROPERTY_CAL_EMAIL_ADDRESS: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define CAL_BACKEND_PROPERTY_CAL_EMAIL_ADDRESS "cal-email-address" + +/** + * CAL_BACKEND_PROPERTY_ALARM_EMAIL_ADDRESS: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define CAL_BACKEND_PROPERTY_ALARM_EMAIL_ADDRESS "alarm-email-address" + +/** + * CAL_BACKEND_PROPERTY_DEFAULT_OBJECT: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define CAL_BACKEND_PROPERTY_DEFAULT_OBJECT "default-object" struct _ECalBackendCache; diff --git a/calendar/libedata-cal/e-data-cal-factory.c b/calendar/libedata-cal/e-data-cal-factory.c index 3e2b937..4413341 100644 --- a/calendar/libedata-cal/e-data-cal-factory.c +++ b/calendar/libedata-cal/e-data-cal-factory.c @@ -711,6 +711,8 @@ e_data_cal_factory_register_gdbus_object (EDataCalFactory *factory, * @is_online: Online mode to set. * * Sets the online mode for all backends created by the given factory. + * + * Since: 3.2 */ void e_data_cal_factory_set_backend_online (EDataCalFactory *factory, diff --git a/calendar/libedata-cal/e-data-cal-view.c b/calendar/libedata-cal/e-data-cal-view.c index db14325..6a63017 100644 --- a/calendar/libedata-cal/e-data-cal-view.c +++ b/calendar/libedata-cal/e-data-cal-view.c @@ -715,6 +715,8 @@ e_data_cal_view_is_stopped (EDataCalView *view) * if there are changes in the objects matching the view search expression. * * Returns: TRUE if the view is completed, FALSE if still in progress. + * + * Since: 3.2 */ gboolean e_data_cal_view_is_completed (EDataCalView *view) @@ -735,6 +737,8 @@ e_data_cal_view_is_completed (EDataCalView *view) * Note: The data pointer in the hash table has no special meaning, it's * only GINT_TO_POINTER(1) for easier checking. Also, field names are * compared case insensitively. + * + * Since: 3.2 **/ /* const */ GHashTable * e_data_cal_view_get_fields_of_interest (EDataCalView *view) @@ -928,7 +932,9 @@ e_data_cal_view_notify_progress (EDataCalView *view, * * Notifies all view listeners of the completion of the view, including a * status code. - */ + * + * Since: 3.2 + **/ void e_data_cal_view_notify_complete (EDataCalView *view, const GError *error) diff --git a/calendar/libedata-cal/e-data-cal.c b/calendar/libedata-cal/e-data-cal.c index ce32805..20ced15 100644 --- a/calendar/libedata-cal/e-data-cal.c +++ b/calendar/libedata-cal/e-data-cal.c @@ -970,11 +970,13 @@ gslist_to_strv (const GSList *lst) } /** - * e_data_cal_notify_open: + * e_data_cal_respond_open: * @cal: A calendar client interface. * @error: Operation error, if any, automatically freed if passed it. * * Notifies listeners of the completion of the open method call. + * + * Since: 3.2 */ void e_data_cal_respond_open (EDataCal *cal, @@ -998,6 +1000,8 @@ e_data_cal_respond_open (EDataCal *cal, * @error: Operation error, if any, automatically freed if passed it. * * Notifies listeners of the completion of the remove method call. + * + * Since: 3.2 */ void e_data_cal_respond_remove (EDataCal *cal, @@ -1024,7 +1028,7 @@ e_data_cal_respond_remove (EDataCal *cal, * * Notifies listeners of the completion of the refresh method call. * - * Since: 2.30 + * Since: 3.2 */ void e_data_cal_respond_refresh (EDataCal *cal, @@ -1049,6 +1053,8 @@ e_data_cal_respond_refresh (EDataCal *cal, * @prop_value: Value of a property * * Notifies listeners of the completion of the get_backend_property method call. + * + * Since: 3.2 */ void e_data_cal_respond_get_backend_property (EDataCal *cal, @@ -1076,6 +1082,8 @@ e_data_cal_respond_get_backend_property (EDataCal *cal, * @error: Operation error, if any, automatically freed if passed it. * * Notifies listeners of the completion of the set_backend_property method call. + * + * Since: 3.2 */ void e_data_cal_respond_set_backend_property (EDataCal *cal, @@ -1100,6 +1108,8 @@ e_data_cal_respond_set_backend_property (EDataCal *cal, * @object: The object retrieved as an iCalendar string. * * Notifies listeners of the completion of the get_object method call. + * + * Since: 3.2 */ void e_data_cal_respond_get_object (EDataCal *cal, @@ -1128,6 +1138,8 @@ e_data_cal_respond_get_object (EDataCal *cal, * @objects: List of retrieved objects. * * Notifies listeners of the completion of the get_object_list method call. + * + * Since: 3.2 */ void e_data_cal_respond_get_object_list (EDataCal *cal, @@ -1158,6 +1170,8 @@ e_data_cal_respond_get_object_list (EDataCal *cal, * * Notifies listeners of the completion of the get_free_busy method call. * To pass actual free/busy objects to the client use e_data_cal_report_free_busy_data(). + * + * Since: 3.2 */ void e_data_cal_respond_get_free_busy (EDataCal *cal, @@ -1183,6 +1197,8 @@ e_data_cal_respond_get_free_busy (EDataCal *cal, * @object: The object created as an iCalendar string. * * Notifies listeners of the completion of the create_object method call. + * + * Since: 3.2 */ void e_data_cal_respond_create_object (EDataCal *cal, @@ -1215,6 +1231,8 @@ e_data_cal_respond_create_object (EDataCal *cal, * @object: The modified object as an iCalendar string. * * Notifies listeners of the completion of the modify_object method call. + * + * Since: 3.2 */ void e_data_cal_respond_modify_object (EDataCal *cal, @@ -1246,6 +1264,8 @@ e_data_cal_respond_modify_object (EDataCal *cal, * when removing instances of a recurring appointment. * * Notifies listeners of the completion of the remove_object method call. + * + * Since: 3.2 */ void e_data_cal_respond_remove_object (EDataCal *cal, @@ -1274,6 +1294,8 @@ e_data_cal_respond_remove_object (EDataCal *cal, * @error: Operation error, if any, automatically freed if passed it. * * Notifies listeners of the completion of the receive_objects method call. + * + * Since: 3.2 */ void e_data_cal_respond_receive_objects (EDataCal *cal, @@ -1299,6 +1321,8 @@ e_data_cal_respond_receive_objects (EDataCal *cal, * @calobj: An iCalendar string representing the object sent. * * Notifies listeners of the completion of the send_objects method call. + * + * Since: 3.2 */ void e_data_cal_respond_send_objects (EDataCal *cal, @@ -1330,6 +1354,8 @@ e_data_cal_respond_send_objects (EDataCal *cal, * @attachment_uris: List of retrieved attachment uri's. * * Notifies listeners of the completion of the get_attachment_uris method call. + * + * Since: 3.2 **/ void e_data_cal_respond_get_attachment_uris (EDataCal *cal, @@ -1359,6 +1385,8 @@ e_data_cal_respond_get_attachment_uris (EDataCal *cal, * @error: Operation error, if any, automatically freed if passed it. * * Notifies listeners of the completion of the discard_alarm method call. + * + * Since: 3.2 **/ void e_data_cal_respond_discard_alarm (EDataCal *cal, @@ -1383,6 +1411,8 @@ e_data_cal_respond_discard_alarm (EDataCal *cal, * @view_path: The new live view path. * * Notifies listeners of the completion of the get_view method call. + * + * Since: 3.2 */ void e_data_cal_respond_get_view (EDataCal *cal, @@ -1411,6 +1441,8 @@ e_data_cal_respond_get_view (EDataCal *cal, * @tzobject: The requested timezone as an iCalendar string. * * Notifies listeners of the completion of the get_timezone method call. + * + * Since: 3.2 */ void e_data_cal_respond_get_timezone (EDataCal *cal, @@ -1433,11 +1465,13 @@ e_data_cal_respond_get_timezone (EDataCal *cal, } /** - * e_data_cal_notify_timezone_added: + * e_data_cal_respond_add_timezone: * @cal: A calendar client interface. * @error: Operation error, if any, automatically freed if passed it. * * Notifies listeners of the completion of the add_timezone method call. + * + * Since: 3.2 */ void e_data_cal_respond_add_timezone (EDataCal *cal, @@ -1455,6 +1489,13 @@ e_data_cal_respond_add_timezone (EDataCal *cal, g_error_free (error); } +/** + * e_data_cal_report_error: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ void e_data_cal_report_error (EDataCal *cal, const gchar *message) @@ -1465,6 +1506,13 @@ e_data_cal_report_error (EDataCal *cal, e_gdbus_cal_emit_backend_error (cal->priv->gdbus_object, message); } +/** + * e_data_cal_report_readonly: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ void e_data_cal_report_readonly (EDataCal *cal, gboolean readonly) @@ -1474,6 +1522,13 @@ e_data_cal_report_readonly (EDataCal *cal, e_gdbus_cal_emit_readonly (cal->priv->gdbus_object, readonly); } +/** + * e_data_cal_report_online: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ void e_data_cal_report_online (EDataCal *cal, gboolean is_online) @@ -1483,9 +1538,13 @@ e_data_cal_report_online (EDataCal *cal, e_gdbus_cal_emit_online (cal->priv->gdbus_object, is_online); } -/* credentilas contains extra information for a source for which authentication is requested. - * This parameter can be NULL to indicate "for this calendar". -*/ +/** + * e_data_cal_report_auth_required: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ void e_data_cal_report_auth_required (EDataCal *cal, const ECredentials *credentials) @@ -1493,6 +1552,10 @@ e_data_cal_report_auth_required (EDataCal *cal, gchar *empty_strv[2]; gchar **strv = NULL; + /* credentilas contains extra information for a source for which + * authentication is requested. This parameter can be NULL to + * indicate "for this calendar". */ + g_return_if_fail (cal != NULL); empty_strv[0] = NULL; @@ -1506,11 +1569,16 @@ e_data_cal_report_auth_required (EDataCal *cal, g_strfreev (strv); } -/* Reports to associated client that opening phase of the cal is finished. - * error being NULL means successfully, otherwise reports an error which happened - * during opening phase. By opening phase is meant a process including successfull - * authentication to the server/storage. - */ +/** + * e_data_cal_report_opened: + * + * Reports to associated client that opening phase of the cal is finished. + * error being NULL means successfully, otherwise reports an error which + * happened during opening phase. By opening phase is meant a process + * including successfull authentication to the server/storage. + * + * Since: 3.2 + **/ void e_data_cal_report_opened (EDataCal *cal, const GError *error) @@ -1524,6 +1592,13 @@ e_data_cal_report_opened (EDataCal *cal, g_strfreev (strv_error); } +/** + * e_data_cal_report_free_busy_data: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ void e_data_cal_report_free_busy_data (EDataCal *cal, const GSList *freebusy) @@ -1539,7 +1614,13 @@ e_data_cal_report_free_busy_data (EDataCal *cal, g_strfreev (strv_freebusy); } -/* Notifies client about certain property value change */ +/** + * e_data_cal_report_backend_property_changed: + * + * Notifies client about certain property value change + * + * Since: 3.2 + **/ void e_data_cal_report_backend_property_changed (EDataCal *cal, const gchar *prop_name, diff --git a/camel/camel-data-cache.c b/camel/camel-data-cache.c index dff4c4b..48e4d32 100644 --- a/camel/camel-data-cache.c +++ b/camel/camel-data-cache.c @@ -519,6 +519,8 @@ camel_data_cache_remove (CamelDataCache *cdc, * @path: Path to the (sub) cache the item exists in. * * Clear cache's content in @path. + * + * Since: 3.2 **/ void camel_data_cache_clear (CamelDataCache *cdc, diff --git a/camel/camel-enums.h b/camel/camel-enums.h index 057bc54..f4e8ba0 100644 --- a/camel/camel-enums.h +++ b/camel/camel-enums.h @@ -144,6 +144,17 @@ typedef enum { CAMEL_FETCH_HEADERS_ALL } CamelFetchHeadersType; +/** + * CamelJunkStatus: + * @CAMEL_JUNK_STATUS_INCONCLUSIVE: + * The junk filter could not determine whether the message is junk. + * @CAMEL_JUNK_STATUS_MESSAGE_IS_JUNK: + * The junk filter believes the message is junk. + * @CAMEL_JUNK_STATUS_MESSAGE_IS_NOT_JUNK: + * The junk filter believes the message is not junk. + * + * These are result codes used when passing messages through a junk filter. + **/ typedef enum { CAMEL_JUNK_STATUS_INCONCLUSIVE, CAMEL_JUNK_STATUS_MESSAGE_IS_JUNK, diff --git a/camel/camel-folder-search.c b/camel/camel-folder-search.c index aa90c2e..5d71725 100644 --- a/camel/camel-folder-search.c +++ b/camel/camel-folder-search.c @@ -1995,7 +1995,18 @@ search_message_location (struct _ESExp *f, return r; } -/* add or subtract given number of months to given time */ +/** + * camel_folder_search_util_add_months: + * @t: Initial time + * @months: number of months to add or subtract + * + * Increases time @t by the given number of months (or decreases, if + * @months is negative). + * + * Returns: a new #time_t value + * + * Since: 3.2 + **/ time_t camel_folder_search_util_add_months (time_t t, gint months) diff --git a/camel/camel-folder.c b/camel/camel-folder.c index dc02610..b11746b 100644 --- a/camel/camel-folder.c +++ b/camel/camel-folder.c @@ -1852,6 +1852,8 @@ camel_folder_set_full_name (CamelFolder *folder, * can be obtained with camel_folder_get_full_name(). * * Returns: the display name of the folder + * + * Since: 3.2 **/ const gchar * camel_folder_get_display_name (CamelFolder *folder) @@ -1868,7 +1870,7 @@ camel_folder_get_display_name (CamelFolder *folder) * * Sets the display name for the folder. * - * Since: 2.32 + * Since: 3.2 **/ void camel_folder_set_display_name (CamelFolder *folder, diff --git a/camel/camel-junk-filter.c b/camel/camel-junk-filter.c index 0805888..d4932d0 100644 --- a/camel/camel-junk-filter.c +++ b/camel/camel-junk-filter.c @@ -25,6 +25,22 @@ camel_junk_filter_default_init (CamelJunkFilterInterface *interface) { } +/** + * camel_junk_filter_classify: + * @junk_filter: a #CamelJunkFilter + * @message: a #CamelMimeMessage + * @status: location to write the #CamelJunkStatus + * @cancellable: optional #GCancellable object, or %NULL + * @error: return location for a #GError, or %NULL + * + * Classifies @message as junk, not junk or inconclusive. + * + * If an error occurs, the function sets @error and returns %FALSE. + * + * Returns: %TRUE if @message was successfully classified + * + * Since: 3.2 + **/ gboolean camel_junk_filter_classify (CamelJunkFilter *junk_filter, CamelMimeMessage *message, @@ -45,6 +61,23 @@ camel_junk_filter_classify (CamelJunkFilter *junk_filter, junk_filter, message, status, cancellable, error); } +/** + * camel_junk_filter_learn_junk: + * @junk_filter: a #CamelJunkFilter + * @message: a #CamelMimeMessage + * @cancellable: optional #GCancellable object, or %NULL + * @error: return location for a #GError, or %NULL + * + * Instructs @junk_filter to classify @message as junk. If using an + * adaptive junk filtering algorithm, explicitly marking @message as + * junk will influence the classification of future messages. + * + * If an error occurs, the function sets @error and returns %FALSE. + * + * Returns: %TRUE if @message was successfully classified + * + * Since: 3.2 + **/ gboolean camel_junk_filter_learn_junk (CamelJunkFilter *junk_filter, CamelMimeMessage *message, @@ -63,6 +96,23 @@ camel_junk_filter_learn_junk (CamelJunkFilter *junk_filter, junk_filter, message, cancellable, error); } +/** + * camel_junk_filter_learn_not_junk: + * @junk_filter: a #CamelJunkFilter + * @message: a #CamelMimeMessage + * @cancellable: optional #GCancellable object, or %NULL + * @error: return location for a #GError, or %NULL + * + * Instructs @junk_filter to classify @message as not junk. If using an + * adaptive junk filtering algorithm, explicitly marking @message as not + * junk will influence the classification of future messages. + * + * If an error occurs, the function sets @error and returns %FALSE. + * + * Returns: %TRUE if @message was successfully classified + * + * Since: 3.2 + **/ gboolean camel_junk_filter_learn_not_junk (CamelJunkFilter *junk_filter, CamelMimeMessage *message, @@ -81,6 +131,22 @@ camel_junk_filter_learn_not_junk (CamelJunkFilter *junk_filter, junk_filter, message, cancellable, error); } +/** + * camel_junk_filter_synchronize: + * @junk_filter: a #CamelJunkFilter + * @cancellable: optional #GCancellable object, or %NULL + * @error: return location for a #GError, or %NULL + * + * Instructs @junk_filter to flush any in-memory caches to disk, if + * applicable. When filtering many messages, delaying this step until + * all messages have been classified can improve performance. + * + * If an error occurs, the function sets @error and returns %FALSE. + * + * Returns: %TRUE if @junk_filter was successfully synchronized + * + * Since: 3.2 + **/ gboolean camel_junk_filter_synchronize (CamelJunkFilter *junk_filter, GCancellable *cancellable, diff --git a/camel/camel-junk-filter.h b/camel/camel-junk-filter.h index bdfce1e..7481b89 100644 --- a/camel/camel-junk-filter.h +++ b/camel/camel-junk-filter.h @@ -47,6 +47,11 @@ G_BEGIN_DECLS +/** + * CamelJunkFilter: + * + * Since: 3.2 + **/ typedef struct _CamelJunkFilter CamelJunkFilter; typedef struct _CamelJunkFilterInterface CamelJunkFilterInterface; diff --git a/camel/camel-network-service.h b/camel/camel-network-service.h index dc8ec91..f816250 100644 --- a/camel/camel-network-service.h +++ b/camel/camel-network-service.h @@ -48,6 +48,11 @@ G_BEGIN_DECLS +/** + * CamelNetworkService: + * + * Since: 3.2 + **/ typedef struct _CamelNetworkService CamelNetworkService; typedef struct _CamelNetworkServiceInterface CamelNetworkServiceInterface; diff --git a/camel/camel-network-settings.h b/camel/camel-network-settings.h index 09aa360..55e7bf6 100644 --- a/camel/camel-network-settings.h +++ b/camel/camel-network-settings.h @@ -47,6 +47,11 @@ G_BEGIN_DECLS +/** + * CamelNetworkSettings: + * + * Since: 3.2 + **/ typedef struct _CamelNetworkSettings CamelNetworkSettings; typedef struct _CamelNetworkSettingsInterface CamelNetworkSettingsInterface; diff --git a/camel/camel-offline-settings.h b/camel/camel-offline-settings.h index 27a9d53..7dcb09b 100644 --- a/camel/camel-offline-settings.h +++ b/camel/camel-offline-settings.h @@ -46,6 +46,14 @@ G_BEGIN_DECLS +/** + * CamelOfflineSettings: + * + * Contains only private data that should be read and manipulated using the + * functions below. + * + * Since: 3.2 + **/ typedef struct _CamelOfflineSettings CamelOfflineSettings; typedef struct _CamelOfflineSettingsClass CamelOfflineSettingsClass; typedef struct _CamelOfflineSettingsPrivate CamelOfflineSettingsPrivate; diff --git a/camel/camel-provider.h b/camel/camel-provider.h index 6e23995..6dde0f6 100644 --- a/camel/camel-provider.h +++ b/camel/camel-provider.h @@ -106,6 +106,11 @@ typedef struct { const gchar *text, *value; } CamelProviderConfEntry; +/** + * CamelProviderPortEntry: + * + * Since: 3.2 + **/ typedef struct { gint port; const gchar *desc; diff --git a/camel/camel-session.c b/camel/camel-session.c index e73e7c7..260ccee 100644 --- a/camel/camel-session.c +++ b/camel/camel-session.c @@ -712,6 +712,8 @@ camel_session_get_service_by_url (CamelSession *session, * camel_session_add_service(). Free the returned list using g_list_free(). * * Returns: an unsorted list of #CamelService objects + * + * Since: 3.2 **/ GList * camel_session_list_services (CamelSession *session) diff --git a/camel/camel-settings.h b/camel/camel-settings.h index d5337fe..75dc833 100644 --- a/camel/camel-settings.h +++ b/camel/camel-settings.h @@ -47,6 +47,14 @@ G_BEGIN_DECLS +/** + * CamelSettings: + * + * Contains only private data that should be read and manipulated using the + * functions below. + * + * Since: 3.2 + **/ typedef struct _CamelSettings CamelSettings; typedef struct _CamelSettingsClass CamelSettingsClass; typedef struct _CamelSettingsPrivate CamelSettingsPrivate; diff --git a/camel/camel-store-settings.h b/camel/camel-store-settings.h index c33079d..bd6ba66 100644 --- a/camel/camel-store-settings.h +++ b/camel/camel-store-settings.h @@ -46,6 +46,14 @@ G_BEGIN_DECLS +/** + * CamelStoreSettings: + * + * Contains only private data that should be read and manipulated using the + * functions below. + * + * Since: 3.2 + **/ typedef struct _CamelStoreSettings CamelStoreSettings; typedef struct _CamelStoreSettingsClass CamelStoreSettingsClass; typedef struct _CamelStoreSettingsPrivate CamelStoreSettingsPrivate; diff --git a/camel/camel-subscribable.h b/camel/camel-subscribable.h index 5a9c0a1..095aec9 100644 --- a/camel/camel-subscribable.h +++ b/camel/camel-subscribable.h @@ -46,6 +46,11 @@ G_BEGIN_DECLS +/** + * CamelSubscribable: + * + * Since: 3.2 + **/ typedef struct _CamelSubscribable CamelSubscribable; typedef struct _CamelSubscribableInterface CamelSubscribableInterface; diff --git a/docs/reference/libebackend/libebackend-docs.xml b/docs/reference/libebackend/libebackend-docs.xml index d12d0c2..423b83d 100644 --- a/docs/reference/libebackend/libebackend-docs.xml +++ b/docs/reference/libebackend/libebackend-docs.xml @@ -15,6 +15,7 @@ + @@ -24,6 +25,10 @@ Index of deprecated symbols + + Index of new symbols in 3.2 + + Index of new symbols in 2.30 diff --git a/docs/reference/libedataserver/libedataserver-sections.txt b/docs/reference/libedataserver/libedataserver-sections.txt index 0289062..ef39457 100644 --- a/docs/reference/libedataserver/libedataserver-sections.txt +++ b/docs/reference/libedataserver/libedataserver-sections.txt @@ -270,6 +270,7 @@ e_list_iterator_get_type
e-operation-pool EOperationPool +EOperationPool e_operation_pool_new e_operation_pool_free e_operation_pool_reserve_opid diff --git a/docs/reference/libedataserver/tmpl/e-operation-pool.sgml b/docs/reference/libedataserver/tmpl/e-operation-pool.sgml index a8854d1..0eab84f 100644 --- a/docs/reference/libedataserver/tmpl/e-operation-pool.sgml +++ b/docs/reference/libedataserver/tmpl/e-operation-pool.sgml @@ -20,6 +20,12 @@ EOperationPool + + + + + + diff --git a/libebackend/e-sqlite3-vfs.c b/libebackend/e-sqlite3-vfs.c index ea767d5..1954e77 100644 --- a/libebackend/e-sqlite3-vfs.c +++ b/libebackend/e-sqlite3-vfs.c @@ -336,6 +336,11 @@ init_sqlite_vfs (void) return NULL; } +/** + * e_sqlite3_vfs_init: + * + * Since: 3.2 + **/ void e_sqlite3_vfs_init (void) { diff --git a/libedataserver/e-client.c b/libedataserver/e-client.c index c2fe993..1d7879c 100644 --- a/libedataserver/e-client.c +++ b/libedataserver/e-client.c @@ -101,6 +101,13 @@ e_client_error_quark (void) return q; } +/** + * e_client_error_to_string: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ const gchar * e_client_error_to_string (EClientError code) { @@ -163,6 +170,8 @@ e_client_error_to_string (EClientError code) * otherwise the given message is used. * * Returned pointer should be freed with g_error_free(). + * + * Since: 3.2 **/ GError * e_client_error_create (EClientError code, @@ -506,7 +515,8 @@ client_ensure_capabilities (EClient *client) * This list, together with inner strings, is owned by the @client. * To check for individual capabilities use e_client_check_capability(). * - * Returns: (element-type utf8) (transfer none): #GSList of const strings of capabilities + * Returns: (element-type utf8) (transfer none): #GSList of const strings + * of capabilities * * Since: 3.2 **/ @@ -567,7 +577,8 @@ e_client_check_capability (EClient *client, * e_client_check_refresh_supported: * @client: A client. * - * Checks whether a client supports explicit refreshing (see e_client_refresh()). + * Checks whether a client supports explicit refreshing + * (see e_client_refresh()). * * Returns: TRUE if the client supports refreshing, FALSE otherwise. * @@ -1453,8 +1464,8 @@ e_client_open_sync (EClient *client, * @callback: callback to call when a result is ready * @user_data: user data for the @callback * - * Removes the backing data for this #EClient. For example, with the file backend this - * deletes the database file. You cannot get it back! + * Removes the backing data for this #EClient. For example, with the file + * backend this deletes the database file. You cannot get it back! * The call is finished by e_client_remove_finish() from the @callback. * * Since: 3.2 @@ -1515,8 +1526,8 @@ e_client_remove_finish (EClient *client, * @cancellable: a #GCancellable; can be %NULL * @error: (out): a #GError to set an error, if any * - * Removes the backing data for this #EClient. For example, with the file backend this - * deletes the database file. You cannot get it back! + * Removes the backing data for this #EClient. For example, with the file + * backend this deletes the database file. You cannot get it back! * * Returns: %TRUE if successful, %FALSE otherwise. * @@ -1641,7 +1652,7 @@ e_client_refresh_sync (EClient *client, * * Note: Pair function for this is e_client_util_strv_to_slist(). * - * Sice: 3.2 + * Since: 3.2 **/ gchar ** e_client_util_slist_to_strv (const GSList *strings) @@ -1675,7 +1686,7 @@ e_client_util_slist_to_strv (const GSList *strings) * * Note: Pair function for this is e_client_util_slist_to_strv(). * - * Sice: 3.2 + * Since: 3.2 **/ GSList * e_client_util_strv_to_slist (const gchar * const *strv) @@ -1751,7 +1762,7 @@ e_client_util_copy_object_slist (GSList *copy_to, * * Frees memory previously allocated by e_client_util_strv_to_slist(). * - * Sice: 3.2 + * Since: 3.2 **/ void e_client_util_free_string_slist (GSList *strings) @@ -1770,7 +1781,7 @@ e_client_util_free_string_slist (GSList *strings) * Calls g_object_unref() on each member of @objects and then frees * also @objects itself. * - * Sice: 3.2 + * Since: 3.2 **/ void e_client_util_free_object_slist (GSList *objects) @@ -2062,6 +2073,8 @@ e_client_get_dbus_proxy (EClient *client) * * Unwraps D-Bus error to local error. @dbus_error is automatically freed. * @dbus_erorr and @out_error can point to the same variable. + * + * Since: 3.2 **/ void e_client_unwrap_dbus_error (EClient *client, @@ -2094,18 +2107,22 @@ e_client_unwrap_dbus_error (EClient *client, * @known_errors_domain: Error domain for @known_errors * @fail_when_none_matched: Whether to fail when none of @known_errors matches * - * The function takes a @dbus_error and tries to find a match in @known_errors for it, - * if it is a G_IO_ERROR, G_IO_ERROR_DBUS_ERROR. If it is anything else then the @dbus_error - * is moved to @client_error. + * The function takes a @dbus_error and tries to find a match in @known_errors + * for it, if it is a G_IO_ERROR, G_IO_ERROR_DBUS_ERROR. If it is anything else + * then the @dbus_error is moved to @client_error. * - * The @fail_when_none_matched influences behaviour. If it's %TRUE, and none of @known_errors matches, - * or this is not a G_IO_ERROR_DBUS_ERROR, then %FALSE is returned and the @client_error - * is left without change. Otherwise, the @fail_when_none_matched is %FALSE, the error is always - * processed and will result in E_CLIENT_ERROR, E_CLIENT_ERROR_OTHER_ERROR if none of @known_error matches. + * The @fail_when_none_matched influences behaviour. If it's %TRUE, and none of + * @known_errors matches, or this is not a G_IO_ERROR_DBUS_ERROR, then %FALSE + * is returned and the @client_error is left without change. Otherwise, the + * @fail_when_none_matched is %FALSE, the error is always processed and will + * result in E_CLIENT_ERROR, E_CLIENT_ERROR_OTHER_ERROR if none of @known_error + * matches. * * Returns: Whether was @dbus_error processed into @client_error. * * Note: The @dbus_error is automatically freed if returned %TRUE. + * + * Since: 3.2 **/ gboolean e_client_util_unwrap_dbus_error (GError *dbus_error, diff --git a/libedataserver/e-client.h b/libedataserver/e-client.h index 9f14d7a..df3338f 100644 --- a/libedataserver/e-client.h +++ b/libedataserver/e-client.h @@ -35,19 +35,93 @@ #define E_IS_CLIENT_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), E_TYPE_CLIENT)) #define E_CLIENT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), E_TYPE_CLIENT, EClientClass)) +/** + * CLIENT_BACKEND_PROPERTY_OPENED: + * + * The "opened" property is "TRUE" when the client is fully opened, + * "FALSE" at all other times. + * + * Since: 3.2 + **/ #define CLIENT_BACKEND_PROPERTY_OPENED "opened" + +/** + * CLIENT_BACKEND_PROPERTY_OPENING: + * + * The "opening" property is "TRUE" when the client is in the process of + * opening, "FALSE" at all other times. + * + * Since: 3.2 + **/ #define CLIENT_BACKEND_PROPERTY_OPENING "opening" + +/** + * CLIENT_BACKEND_PROPERTY_ONLINE: + * + * The "online" property is "TRUE" when the client is fully opened and + * online, "FALSE" at all other times. See also e_client_is_online(). + * + * Since: 3.2 + **/ #define CLIENT_BACKEND_PROPERTY_ONLINE "online" + +/** + * CLIENT_BACKEND_PROPERTY_READONLY: + * + * The "online" property is "TRUE" if the backend has only read access + * to its data, "FALSE" if the backend can modify its data. See also + * e_client_is_readonly(). + * + * Since: 3.2 + **/ #define CLIENT_BACKEND_PROPERTY_READONLY "readonly" + +/** + * CLIENT_BACKEND_PROPERTY_CACHE_DIR: + * + * The "cache-dir" property indicates the backend's local directory for + * cached data. + * + * Since: 3.2 + **/ #define CLIENT_BACKEND_PROPERTY_CACHE_DIR "cache-dir" + +/** + * CLIENT_BACKEND_PROPERTY_CAPABILITIES: + * + * The "capabilities" property is a comma-separated list of capabilities + * supported by the backend. The preferred method of retrieving and working + * with capabilities is e_client_get_capabilities() and + * e_client_check_capability(). + * + * Since: 3.2 + **/ #define CLIENT_BACKEND_PROPERTY_CAPABILITIES "capabilities" +/** + * E_CLIENT_ERROR: + * + * Error domain for #EClient operations. Errors in this domain will be + * from the #EClientError enumeration. See #GError for more information + * on error domains. + * + * Since: 3.2 + **/ #define E_CLIENT_ERROR e_client_error_quark () G_BEGIN_DECLS GQuark e_client_error_quark (void) G_GNUC_CONST; +/** + * EClientError: + * + * FIXME Document each code. + * + * Error codes for #EClient operations. + * + * Since: 3.2 + **/ typedef enum { E_CLIENT_ERROR_INVALID_ARG, E_CLIENT_ERROR_BUSY, @@ -75,6 +149,14 @@ typedef enum { const gchar * e_client_error_to_string (EClientError code); GError * e_client_error_create (EClientError code, const gchar *custom_msg); +/** + * EClient: + * + * Contains only private data that should be read and manipulated using the + * functions below. + * + * Since: 3.2 + **/ typedef struct _EClient EClient; typedef struct _EClientClass EClientClass; typedef struct _EClientPrivate EClientPrivate; @@ -176,6 +258,11 @@ GSList * e_client_util_parse_comma_strings (const gchar *strings); typedef struct _EClientErrorsList EClientErrorsList; +/** + * EClientErrorsList: + * + * Since: 3.2 + **/ struct _EClientErrorsList { const gchar *name; gint err_code; diff --git a/libedataserver/e-credentials.c b/libedataserver/e-credentials.c index a32cf41..f2cfb62 100644 --- a/libedataserver/e-credentials.c +++ b/libedataserver/e-credentials.c @@ -49,6 +49,13 @@ key_equal (gconstpointer str1, return g_ascii_strcasecmp (str1, str2) == 0; } +/** + * e_credentials_new: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ ECredentials * e_credentials_new (void) { @@ -62,15 +69,23 @@ e_credentials_new (void) return credentials; } -/* Expects @keys as NULL terminate list of strings "key:encoded_value". - * The same can be returned from e_credentials_to_strv (). -*/ +/** + * e_credentials_new_strv: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ ECredentials * e_credentials_new_strv (const gchar * const *keys) { ECredentials *credentials; gint ii; + /* Expects @keys as NULL terminated list of strings + * "key:encoded_value". The same can be returned from + * e_credentials_to_strv (). */ + g_return_val_if_fail (keys != NULL, NULL); credentials = e_credentials_new (); @@ -88,7 +103,13 @@ e_credentials_new_strv (const gchar * const *keys) return credentials; } -/* NULL-terminated list of string pairs ; value is in a clear form */ +/** + * e_credentials_new_args: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ ECredentials * e_credentials_new_args (const gchar *key, ...) @@ -96,6 +117,9 @@ e_credentials_new_args (const gchar *key, ECredentials *credentials; va_list va; + /* NULL-terminated list of string pairs ; value is + * in a clear form. */ + g_return_val_if_fail (key != NULL, NULL); credentials = e_credentials_new (); @@ -124,6 +148,13 @@ copy_keys_cb (gpointer key, g_hash_table_insert (hash_table, g_strdup (key), g_strdup (value)); } +/** + * e_credentials_new_clone: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ ECredentials * e_credentials_new_clone (const ECredentials *credentials) { @@ -140,6 +171,13 @@ e_credentials_new_clone (const ECredentials *credentials) return res; } +/** + * e_credentials_free: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ void e_credentials_free (ECredentials *credentials) { @@ -168,11 +206,19 @@ add_to_array_cb (gpointer key, } } -/* Returns NULL-terminated array of strings with keys and encoded values; - * To read them back pass this pointer to e_credentials_new (). As it returns - * newly allocated string then this should be freed with g_strfreev () - * when no longer needed. -*/ +/** + * e_credentials_to_strv: + * @credentials: an #ECredentials + * + * Returns %NULL-terminated array of strings with keys and encoded values; + * To read them back pass this pointer to e_credentials_new(). As it returns + * newly allocated string then this should be freed with g_strfreev() when no + * longer needed. + * + * Returns: a %NULL-terminated array of key/value strings + * + * Since: 3.2 + **/ gchar ** e_credentials_to_strv (const ECredentials *credentials) { @@ -245,10 +291,18 @@ decode_string (const gchar *encoded) return res; } -/* sets value for a key, if value is NULL or an empty string then the key is removed. - * the value is supposed to be in a clear form (unencoded). - * 'key' cannot contain colon. -*/ +/** + * e_credentials_set: + * @credentials: an #ECredentials + * @key: a key string + * @value: a value string + * + * Sets value for @key, if @value is %NULL or an empty string then @key is + * removed. The value is supposed to be in a clear form (unencoded). + * @key cannot contain colon. + * + * Since: 3.2 + **/ void e_credentials_set (ECredentials *credentials, const gchar *key, @@ -271,15 +325,22 @@ e_credentials_set (ECredentials *credentials, } } -/* Returned pointer should be freed with e_credentials_util_safe_free_string() - * when no longer needed. -*/ +/** + * e_credentials_get: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ gchar * e_credentials_get (const ECredentials *credentials, const gchar *key) { const gchar *stored; + /* Returned pointer should be freed with + * e_credentials_util_safe_free_string() when no longer needed. */ + g_return_val_if_fail (credentials != NULL, NULL); g_return_val_if_fail (credentials->priv != NULL, NULL); g_return_val_if_fail (credentials->priv->keys != NULL, NULL); @@ -293,10 +354,19 @@ e_credentials_get (const ECredentials *credentials, return decode_string (stored); } -/* peeks value for a key, in a clear form. The value is valid until free - * of the @credentials structure or until the key value is rewritten - * by e_credentials_set () -*/ +/** + * e_credentials_peek: + * @credentials: an #ECredentials + * @key: a key string + * + * Peeks at the value for @key, in a clear form. The returned value is valid + * until free of the @credentials structure or until the key value is rewritten + * by e_credentials_set(). + * + * Returns: the value for @key + * + * Since: 3.2 + **/ const gchar * e_credentials_peek (ECredentials *credentials, const gchar *key) @@ -341,7 +411,18 @@ check_equal_cb (gpointer key, ed->equal = ed->equal && g_strcmp0 (value, g_hash_table_lookup (ed->keys, key)) == 0; } -/* Returns whether two credential structurs contain the same keys with same values */ +/** + * e_credentials_equal: + * @credentials1: an #ECredentials + * @credentials2: another #ECredentials + * + * Returns whether two #ECredential structures contain the same keys with + * same values. + * + * Returns: %TRUE if they are equal, %FALSE otherwise + * + * Since: 3.2 + **/ gboolean e_credentials_equal (const ECredentials *credentials1, const ECredentials *credentials2) @@ -373,7 +454,18 @@ e_credentials_equal (const ECredentials *credentials1, return ed.equal; } -/* Returns whether two credentials structures has same keys. Key names are NULL-terminated. */ +/** + * e_credentials_equal_keys: + * @credentials1: an #ECredentials + * @credentials2: another #ECredentials + * + * Returns whether two #ECredentials structures have the same keys. Key names + * are NULL-terminated. + * + * Returns: %TRUE if the key sets match, %FALSE otherwise + * + * Since: 3.2 + **/ gboolean e_credentials_equal_keys (const ECredentials *credentials1, const ECredentials *credentials2, @@ -405,8 +497,15 @@ e_credentials_equal_keys (const ECredentials *credentials1, } /** + * e_credentials_has_key: + * @credentials: an #ECredentials + * @key: a key string + * * Returns whether @credentials contains @key. - * This key is non-NULL and non-empty string. + * + * Returns: %TRUE if @credentials contains @key, %FALSE otherwise + * + * Since: 3.2 **/ gboolean e_credentials_has_key (const ECredentials *credentials, @@ -421,6 +520,16 @@ e_credentials_has_key (const ECredentials *credentials, return g_hash_table_lookup (credentials->priv->keys, key) != NULL; } +/** + * e_credentials_keys_size: + * @credentials: an #ECredentials + * + * Returns the number of keys in @credentials. + * + * Returns: the number of keys in @credentials + * + * Since: 3.2 + **/ guint e_credentials_keys_size (const ECredentials *credentials) { @@ -444,10 +553,18 @@ gather_key_names (gpointer key, *slist = g_slist_prepend (*slist, key); } -/* Returns newly allocated list of key names stored in the credentials strucutre; - * strings are internal credentials values, only the list is newly allocated. - * Free the list with g_slist_free () when no longer needed. -*/ +/** + * e_credentials_list_keys: + * @credentials: an #ECredentials + * + * Returns a newly-allocated #GSList of key names stored in @credentials. + * The key names are internal credentials values and should not be modified + * or freed. Free the list with g_slist_free() when no longer needed. + * + * Returns: a newly-allocated #GSList of key names + * + * Since: 3.2 + **/ GSList * e_credentials_list_keys (const ECredentials *credentials) { @@ -457,12 +574,20 @@ e_credentials_list_keys (const ECredentials *credentials) g_return_val_if_fail (credentials->priv != NULL, NULL); g_return_val_if_fail (credentials->priv->keys != NULL, NULL); + /* XXX g_hash_table_get_keys() would have been + * easier had we used #GList instead. */ g_hash_table_foreach (credentials->priv->keys, gather_key_names, &keys); return g_slist_reverse (keys); } -/* Removes all keys in once. */ +/** + * e_credentials_clear: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ void e_credentials_clear (ECredentials *credentials) { @@ -475,6 +600,13 @@ e_credentials_clear (ECredentials *credentials) g_hash_table_remove_all (credentials->priv->keys); } +/** + * e_credentials_clear_peek: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ void e_credentials_clear_peek (ECredentials *credentials) { @@ -485,6 +617,13 @@ e_credentials_clear_peek (ECredentials *credentials) g_hash_table_remove_all (credentials->priv->peek_keys); } +/** + * e_credentials_util_safe_free_string: + * + * FIXME Document me. + * + * Since: 3.2 + **/ void e_credentials_util_safe_free_string (gchar *str) { @@ -513,9 +652,13 @@ static struct _PromptFlags { { E_CREDENTIALS_PROMPT_FLAG_PASSPHRASE, "passphrase", TRUE } }; -/* Returned pointer can be passed to e_credentials_util_string_to prompt_flags() - * to decode it back to flags. Free returned pointer with g_free (). -*/ +/** + * e_credentials_util_prompt_flags_to_string: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ gchar * e_credentials_util_prompt_flags_to_string (guint prompt_flags) { @@ -523,6 +666,10 @@ e_credentials_util_prompt_flags_to_string (guint prompt_flags) guint masked = prompt_flags & E_CREDENTIALS_PROMPT_FLAG_REMEMBER_MASK; GString *str = g_string_new (""); + /* Returned pointer can be passed to + * e_credentials_util_string_to prompt_flags() to decode + * it back to flags. Free returned pointer with g_free(). */ + for (ii = 0; ii < G_N_ELEMENTS (PromptFlags); ii++) { const gchar *add = NULL; @@ -545,6 +692,13 @@ e_credentials_util_prompt_flags_to_string (guint prompt_flags) return g_string_free (str, FALSE); } +/** + * e_credentials_util_string_to_prompt_flags: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ guint e_credentials_util_string_to_prompt_flags (const gchar *prompt_flags_string) { diff --git a/libedataserver/e-credentials.h b/libedataserver/e-credentials.h index d6b9992..acbc436 100644 --- a/libedataserver/e-credentials.h +++ b/libedataserver/e-credentials.h @@ -29,19 +29,97 @@ G_BEGIN_DECLS typedef struct _ECredentials ECredentials; typedef struct _ECredentialsPrivate ECredentialsPrivate; +/** + * ECredentials: + * + * Contains only private data that should be read and manipulated using the + * functions below. + * + * Since: 3.2 + **/ struct _ECredentials { ECredentialsPrivate *priv; }; +/** + * E_CREDENTIALS_KEY_USERNAME: + * + * FIXME Docment me. + * + * Since: 3.2 + **/ #define E_CREDENTIALS_KEY_USERNAME "username" + +/** + * E_CREDENTIALS_KEY_PASSWORD: + * + * FIXME Document me. + * + * Since: 3.2 + **/ #define E_CREDENTIALS_KEY_PASSWORD "password" + +/** + * E_CREDENTIALS_KEY_AUTH_METHOD: + * + * FIXME Document me. + * + * Since: 3.2 + **/ #define E_CREDENTIALS_KEY_AUTH_METHOD "auth-method" + +/** + * E_CREDENTIALS_KEY_PROMPT_TITLE: + * + * FIXME Document me. + * + * Since: 3.2 + **/ #define E_CREDENTIALS_KEY_PROMPT_TITLE "prompt-title" + +/** + * E_CREDENTIALS_KEY_PROMPT_TEXT: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define E_CREDENTIALS_KEY_PROMPT_TEXT "prompt-text" + +/** + * E_CREDENTIALS_KEY_PROMPT_REASON: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define E_CREDENTIALS_KEY_PROMPT_REASON "prompt-reason" + +/** + * E_CREDENTIALS_KEY_PROMPT_KEY: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ #define E_CREDENTIALS_KEY_PROMPT_KEY "prompt-key" + +/** + * E_CREDENTIALS_KEY_PROMPT_FLAGS: + * + * FIXME Document me. + * + * Since: 3.2 + **/ #define E_CREDENTIALS_KEY_PROMPT_FLAGS "prompt-flags" +/** + * ECredentialsPromptFlags: + * + * FIXME Document me. + * + * Since: 3.2 + **/ /* this is 1:1 with EPasswordsRememberType */ typedef enum { E_CREDENTIALS_PROMPT_FLAG_REMEMBER_NEVER, diff --git a/libedataserver/e-data-server-util.c b/libedataserver/e-data-server-util.c index a08299e..4c0310a 100644 --- a/libedataserver/e-data-server-util.c +++ b/libedataserver/e-data-server-util.c @@ -1243,6 +1243,13 @@ dump_left_at_exit_cb (void) G_UNLOCK (ptr_tracker); } +/** + * e_pointer_tracker_track_with_info: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ void e_pointer_tracker_track_with_info (gpointer ptr, const gchar *info) @@ -1267,6 +1274,13 @@ e_pointer_tracker_track_with_info (gpointer ptr, G_UNLOCK (ptr_tracker); } +/** + * e_pointer_tracker_untrack: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ void e_pointer_tracker_untrack (gpointer ptr) { @@ -1284,6 +1298,13 @@ e_pointer_tracker_untrack (gpointer ptr) G_UNLOCK (ptr_tracker); } +/** + * e_pointer_tracker_dump: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ void e_pointer_tracker_dump (void) { diff --git a/libedataserver/e-data-server-util.h b/libedataserver/e-data-server-util.h index 0a52578..9355d5b 100644 --- a/libedataserver/e-data-server-util.h +++ b/libedataserver/e-data-server-util.h @@ -73,7 +73,16 @@ gint e_data_server_util_get_dbus_call_timeout void e_data_server_util_set_dbus_call_timeout (gint timeout_msec); -#define e_pointer_tracker_track(ptr) e_pointer_tracker_track_with_info (ptr, G_STRFUNC) +/** + * e_pointer_tracker_track: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ +#define e_pointer_tracker_track(ptr) \ + (e_pointer_tracker_track_with_info ((ptr), G_STRFUNC)) + void e_pointer_tracker_track_with_info (gpointer ptr, const gchar *info); void e_pointer_tracker_untrack (gpointer ptr); void e_pointer_tracker_dump (void); diff --git a/libedataserver/e-operation-pool.c b/libedataserver/e-operation-pool.c index e6c784f..4f990f4 100644 --- a/libedataserver/e-operation-pool.c +++ b/libedataserver/e-operation-pool.c @@ -29,6 +29,13 @@ struct _EOperationPool { guint32 last_opid; }; +/** + * e_operation_pool_new: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ EOperationPool * e_operation_pool_new (guint max_threads, GFunc thread_func, @@ -59,6 +66,13 @@ e_operation_pool_new (guint max_threads, return pool; } +/** + * e_operation_pool_free: + * + * FIXME: Document me. + * + * Since: 3.2 + **/ void e_operation_pool_free (EOperationPool *pool) { @@ -70,10 +84,18 @@ e_operation_pool_free (EOperationPool *pool) g_free (pool); } -/* Reserves new operation ID, which is returned. This operation ID may - * be released by e_operation_pool_release_opid () when the operation +/** + * e_operation_pool_reserve_opid: + * @pool: an #EOperationPool + * + * Reserves new operation ID, which is returned. This operation ID may + * be released by e_operation_pool_release_opid() when the operation * is finished. -*/ + * + * Returns: a new operation ID + * + * Since: 3.2 + **/ guint32 e_operation_pool_reserve_opid (EOperationPool *pool) { @@ -103,7 +125,15 @@ e_operation_pool_reserve_opid (EOperationPool *pool) return opid; } -/* Releases operation ID previously reserved by e_operation_pool_reserve_opid(). */ +/** + * e_operation_pool_release_opid: + * @pool: an #EOperationPool + * @opid: an operation ID + * + * Releases @opid previously reserved by e_operation_pool_reserve_opid(). + * + * Since: 3.2 + **/ void e_operation_pool_release_opid (EOperationPool *pool, guint32 opid) @@ -117,9 +147,16 @@ e_operation_pool_release_opid (EOperationPool *pool, g_mutex_unlock (pool->ops_lock); } -/* Pushes operation to be processed. 'opdata' is passed to the function - * provided in e_operation_pool_new (). -*/ +/** + * e_operation_pool_push: + * @pool: an #EOperationPool + * @opdata: user data for the operation + * + * Pushes an operation to be processed. @opdata is passed to the function + * provided in e_operation_pool_new(). + * + * Since: 3.2 + **/ void e_operation_pool_push (EOperationPool *pool, gpointer opdata) diff --git a/libedataserver/e-operation-pool.h b/libedataserver/e-operation-pool.h index 8696ea3..f787558 100644 --- a/libedataserver/e-operation-pool.h +++ b/libedataserver/e-operation-pool.h @@ -24,6 +24,14 @@ #include +/** + * EOperationPool: + * + * Contains only private data that should be read and manipulated using the + * functions below. + * + * Since: 3.2 + **/ typedef struct _EOperationPool EOperationPool; EOperationPool *e_operation_pool_new (guint max_threads, GFunc thread_func, gpointer user_data); diff --git a/libedataserverui/e-categories-editor.h b/libedataserverui/e-categories-editor.h index 2896987..04a2410 100644 --- a/libedataserverui/e-categories-editor.h +++ b/libedataserverui/e-categories-editor.h @@ -47,6 +47,14 @@ typedef struct _ECategoriesEditor ECategoriesEditor; typedef struct _ECategoriesEditorClass ECategoriesEditorClass; typedef struct _ECategoriesEditorPrivate ECategoriesEditorPrivate; +/** + * ECategoriesEditor: + * + * Contains only private data that should be read and manipulated using the + * functions below. + * + * Since: 3.2 + **/ struct _ECategoriesEditor { GtkTable parent; ECategoriesEditorPrivate *priv; diff --git a/libedataserverui/e-categories-selector.h b/libedataserverui/e-categories-selector.h index 75dbfa5..fa416bc 100644 --- a/libedataserverui/e-categories-selector.h +++ b/libedataserverui/e-categories-selector.h @@ -47,6 +47,14 @@ typedef struct _ECategoriesSelector ECategoriesSelector; typedef struct _ECategoriesSelectorClass ECategoriesSelectorClass; typedef struct _ECategoriesSelectorPrivate ECategoriesSelectorPrivate; +/** + * ECategoriesSelector: + * + * Contains only private data that should be read and manipulated using the + * functions below. + * + * Since: 3.2 + **/ struct _ECategoriesSelector { GtkTreeView parent; ECategoriesSelectorPrivate *priv; diff --git a/libedataserverui/e-category-editor.h b/libedataserverui/e-category-editor.h index 19c706b..e17290b 100644 --- a/libedataserverui/e-category-editor.h +++ b/libedataserverui/e-category-editor.h @@ -47,6 +47,14 @@ typedef struct _ECategoryEditor ECategoryEditor; typedef struct _ECategoryEditorClass ECategoryEditorClass; typedef struct _ECategoryEditorPrivate ECategoryEditorPrivate; +/** + * ECategoryEditor: + * + * Contains only private data that should be read and manipulated using the + * functions below. + * + * Since: 3.2 + **/ struct _ECategoryEditor { GtkDialog parent; ECategoryEditorPrivate *priv; diff --git a/libedataserverui/e-client-utils.c b/libedataserverui/e-client-utils.c index 6d05a90..948bc17 100644 --- a/libedataserverui/e-client-utils.c +++ b/libedataserverui/e-client-utils.c @@ -39,6 +39,8 @@ * e_client_utils_new: * * Proxy function for e_book_client_utils_new() and e_cal_client_utils_new(). + * + * Since: 3.2 **/ EClient * e_client_utils_new (ESource *source, @@ -75,6 +77,8 @@ e_client_utils_new (ESource *source, * e_client_utils_new_from_uri: * * Proxy function for e_book_client_utils_new_from_uri() and e_cal_client_utils_new_from_uri(). + * + * Since: 3.2 **/ EClient * e_client_utils_new_from_uri (const gchar *uri, @@ -110,6 +114,8 @@ e_client_utils_new_from_uri (const gchar *uri, * e_client_utils_new_system: * * Proxy function for e_book_client_utils_new_system() and e_cal_client_utils_new_system(). + * + * Since: 3.2 **/ EClient * e_client_utils_new_system (EClientSourceType source_type, @@ -142,6 +148,8 @@ e_client_utils_new_system (EClientSourceType source_type, * e_client_utils_new_default: * * Proxy function for e_book_client_utils_new_default() and e_cal_client_utils_new_default(). + * + * Since: 3.2 **/ EClient * e_client_utils_new_default (EClientSourceType source_type, @@ -174,6 +182,8 @@ e_client_utils_new_default (EClientSourceType source_type, * e_client_utils_set_default: * * Proxy function for e_book_client_utils_set_default() and e_book_client_utils_set_default(). + * + * Since: 3.2 **/ gboolean e_client_utils_set_default (EClient *client, @@ -208,6 +218,8 @@ e_client_utils_set_default (EClient *client, * e_client_utils_set_default_source: * * Proxy function for e_book_client_utils_set_default_source() and e_cal_client_utils_set_default_source(). + * + * Since: 3.2 **/ gboolean e_client_utils_set_default_source (ESource *source, @@ -244,6 +256,8 @@ e_client_utils_set_default_source (ESource *source, * e_client_utils_get_sources: * * Proxy function for e_book_client_utils_get_sources() and e_cal_client_utils_get_sources(). + * + * Since: 3.2 **/ gboolean e_client_utils_get_sources (ESourceList **sources, @@ -760,14 +774,19 @@ get_prompt_key (EClient *client, return uri_str; } -/* This function is suitable as a handler for EClient::authenticate signal. +/** + * e_client_utils_authenticate_handler: + * + * This function is suitable as a handler for EClient::authenticate signal. * It takes care of all the password prompt and such and returns TRUE if * credentials (password) were provided. Thus just connect it to that signal * and it'll take care of everything else. * * gtk_window_parent is user_data passed into the callback. It can be a pointer * to GtkWindow, used as a parent for a pasword prompt dialog. -*/ + * + * Since: 3.2 + **/ gboolean e_client_utils_authenticate_handler (EClient *client, ECredentials *credentials, @@ -909,7 +928,10 @@ e_client_utils_forget_password (EClient *client) g_free (prompt_key); } -/* Asks for a password based on the provided credentials information. +/** + * e_credentials_authenticate_helper: + * + * Asks for a password based on the provided credentials information. * Credentials should have set following keys: * E_CREDENTIALS_KEY_USERNAME * E_CREDENTIALS_KEY_PROMPT_KEY @@ -919,7 +941,9 @@ e_client_utils_forget_password (EClient *client) * * When this returns TRUE, then the structure contains E_CREDENTIALS_KEY_PASSWORD set * as entered by a user. -*/ + * + * Since: 3.2 + **/ gboolean e_credentials_authenticate_helper (ECredentials *credentials, GtkWindow *parent, diff --git a/libedataserverui/e-client-utils.h b/libedataserverui/e-client-utils.h index 130a796..1582a03 100644 --- a/libedataserverui/e-client-utils.h +++ b/libedataserverui/e-client-utils.h @@ -28,6 +28,11 @@ G_BEGIN_DECLS +/** + * EClientSourceType: + * + * Since: 3.2 + **/ typedef enum { E_CLIENT_SOURCE_TYPE_CONTACTS, E_CLIENT_SOURCE_TYPE_EVENTS, @@ -36,6 +41,11 @@ typedef enum { E_CLIENT_SOURCE_TYPE_LAST } EClientSourceType; +/** + * EClientUtilsAuthenticateHandler: + * + * Since: 3.2 + **/ typedef gboolean (* EClientUtilsAuthenticateHandler) (EClient *client, ECredentials *credentials, gpointer user_data); EClient * e_client_utils_new (ESource *source, EClientSourceType source_type, GError **error); diff --git a/libedataserverui/e-contact-store.c b/libedataserverui/e-contact-store.c index 2f75427..70197ca 100644 --- a/libedataserverui/e-contact-store.c +++ b/libedataserverui/e-contact-store.c @@ -912,6 +912,8 @@ query_contact_source (EContactStore *contact_store, * Gets the #EBookClient that provided the contact at @iter. * * Returns: An #EBookClient. + * + * Since: 3.2 **/ EBookClient * e_contact_store_get_client (EContactStore *contact_store, @@ -986,6 +988,8 @@ e_contact_store_find_contact (EContactStore *contact_store, * * Returns: A #GSList of pointers to #EBookClient. The caller owns the list, * but not the book clients. + * + * Since: 3.2 **/ GSList * e_contact_store_get_clients (EContactStore *contact_store) @@ -1015,6 +1019,8 @@ e_contact_store_get_clients (EContactStore *contact_store) * * Adds @book_client to the list of book clients that provide contacts for @contact_store. * The @contact_store adds a reference to @book_client, if added. + * + * Since: 3.2 **/ void e_contact_store_add_client (EContactStore *contact_store, @@ -1050,6 +1056,8 @@ e_contact_store_add_client (EContactStore *contact_store, * @book_client: an #EBookClient * * Removes @book from the list of book clients that provide contacts for @contact_store. + * + * Since: 3.2 **/ void e_contact_store_remove_client (EContactStore *contact_store, -- 2.7.4