GNOME.org
 

[evolution-data-server/documentation-effort] Work in progress, fixing gtk-doc comments and removing warnings from the gtk-doc build.

commit 13d114628cb10f1749c1746aa830f331b4bd8d4e
Author: Tristan Van Berkom <tristanvb openismus com>
Date:   Tue Nov 12 15:40:36 2013 +0900

    Work in progress, fixing gtk-doc comments and removing warnings from the gtk-doc build.

 addressbook/libebook-contacts/e-address-western.h  |   12 ++++
 .../libebook-contacts/e-phone-number-private.h     |    9 +---
 addressbook/libebook/e-book-client.c               |    4 +-
 addressbook/libebook/e-book.h                      |   38 ++++++++++++++
 .../libedata-book/e-book-backend-sqlitedb.c        |   31 ++++--------
 addressbook/libedata-book/e-book-backend.h         |   53 +++++++++++++++++++
 calendar/libecal/e-cal-client-view.c               |   17 ++++++-
 calendar/libecal/e-cal-client.h                    |    4 +-
 calendar/libecal/e-cal-component.c                 |    3 +-
 calendar/libecal/e-cal-system-timezone.c           |    7 ++-
 calendar/libecal/e-cal-util.c                      |   24 +++++----
 calendar/libedata-cal/e-cal-backend-intervaltree.c |    2 +-
 calendar/libedata-cal/e-cal-backend-store.c        |   18 +++++--
 libebackend/e-authentication-mediator.h            |    9 +++
 libebackend/e-authentication-session.h             |   15 +++++
 libebackend/e-backend-factory.h                    |   13 +++++
 libebackend/e-backend.c                            |    5 +-
 libebackend/e-backend.h                            |   15 +++++
 libedataserver/e-cancellable-locks.c               |    2 +-
 libedataserver/e-client.c                          |   55 ++++++++++++++++----
 libedataserver/e-operation-pool.c                  |    6 +-
 libedataserver/e-sexp.c                            |    4 +-
 22 files changed, 277 insertions(+), 69 deletions(-)
---
diff --git a/addressbook/libebook-contacts/e-address-western.h 
b/addressbook/libebook-contacts/e-address-western.h
index a4dd8de..ae2a7b8 100644
--- a/addressbook/libebook-contacts/e-address-western.h
+++ b/addressbook/libebook-contacts/e-address-western.h
@@ -9,6 +9,18 @@
 
 G_BEGIN_DECLS
 
+/**
+ * EAddressWestern:
+ * @po_box: PO Box.
+ * @extended: TODO, we're not sure what this is.
+ * @street: Street name
+ * @locality: City or town
+ * @region: State or province
+ * @postal_code: Postal Code
+ * @country: Country
+ *
+ * Western address structure.
+ */
 typedef struct {
 
        /* Public */
diff --git a/addressbook/libebook-contacts/e-phone-number-private.h 
b/addressbook/libebook-contacts/e-phone-number-private.h
index 0f80491..e9a855e 100644
--- a/addressbook/libebook-contacts/e-phone-number-private.h
+++ b/addressbook/libebook-contacts/e-phone-number-private.h
@@ -22,15 +22,10 @@
 /* NOTE: Keeping API documentation in this header file because gtkdoc-mkdb
  * explicitly only scans .h and .c files, but ignores .cpp files. */
 
-/**
- * SECTION: e-phone-utils
- * @include: libedataserver/libedataserver.h
- * @short_description: Phone number support
- *
+/*
  * This modules provides utility functions for parsing and formatting
  * phone numbers. Under the hood it uses Google's libphonenumber.
- **/
-
+ */
 #if !defined (__LIBEBOOK_CONTACTS_H_INSIDE__) && !defined (LIBEBOOK_CONTACTS_COMPILATION)
 #error "Only <libebook-contacts/libebook-contacts.h> should be included directly."
 #endif
diff --git a/addressbook/libebook/e-book-client.c b/addressbook/libebook/e-book-client.c
index 421ad02..0d9e548 100644
--- a/addressbook/libebook/e-book-client.c
+++ b/addressbook/libebook/e-book-client.c
@@ -1120,8 +1120,8 @@ e_book_client_class_init (EBookClientClass *class)
                PROP_LOCALE,
                g_param_spec_string (
                        "locale",
-                       NULL,
-                       NULL,
+                       "Locale",
+                       "The currently active locale for this addressbook",
                        NULL,
                        G_PARAM_READABLE |
                        G_PARAM_STATIC_STRINGS));
diff --git a/addressbook/libebook/e-book.h b/addressbook/libebook/e-book.h
index fb00827..5b08561 100644
--- a/addressbook/libebook/e-book.h
+++ b/addressbook/libebook/e-book.h
@@ -48,6 +48,8 @@ typedef void (*EBookCallback) (EBook *book, EBookStatus status, gpointer closure
  * @closure: the callback closure
  *
  * Since: 2.32
+ *
+ * Deprecated: 3.2: Use #EBookClient instead 
  **/
 typedef void (*EBookAsyncCallback) (EBook *book, const GError *error, gpointer closure);
 
@@ -59,6 +61,8 @@ typedef void (*EBookAsyncCallback) (EBook *book, const GError *error, gpointer c
  * @closure: the callback closure
  *
  * Since: 2.32
+ *
+ * Deprecated: 3.2: Use #EBookClient instead
  **/
 typedef void (*EBookOpenProgressCallback)     (EBook          *book,
                                               const gchar     *status_message,
@@ -78,6 +82,8 @@ typedef void (*EBookEListCallback)   (EBook *book, EBookStatus status, EList *li
  * @closure: the callback closure
  *
  * Since: 2.32
+ *
+ * Deprecated: 3.2: Use #EBookClient instead
  **/
 typedef void (*EBookIdAsyncCallback)       (EBook *book, const GError *error, const gchar *id, gpointer 
closure);
 
@@ -89,6 +95,8 @@ typedef void (*EBookIdAsyncCallback)       (EBook *book, const GError *error, co
  * @closure: the callback closure
  *
  * Since: 2.32
+ *
+ * Deprecated: 3.2: Use #EBookClient instead
  **/
 typedef void (*EBookContactAsyncCallback)  (EBook *book, const GError *error, EContact *contact, gpointer 
closure);
 
@@ -100,6 +108,8 @@ typedef void (*EBookContactAsyncCallback)  (EBook *book, const GError *error, EC
  * @closure: the callback closure
  *
  * Since: 2.32
+ *
+ * Deprecated: 3.2: Use #EBookClient instead
  **/
 typedef void (*EBookListAsyncCallback)     (EBook *book, const GError *error, GList *list, gpointer closure);
 
@@ -111,6 +121,8 @@ typedef void (*EBookListAsyncCallback)     (EBook *book, const GError *error, GL
  * @closure: the callback closure
  *
  * Since: 2.32
+ *
+ * Deprecated: 3.2: Use #EBookClient instead
  **/
 typedef void (*EBookBookViewAsyncCallback) (EBook *book, const GError *error, EBookView *book_view, gpointer 
closure);
 
@@ -122,18 +134,43 @@ typedef void (*EBookBookViewAsyncCallback) (EBook *book, const GError *error, EB
  * @closure: the callback closure
  *
  * Since: 2.32
+ *
+ * Deprecated: 3.2: Use #EBookClient instead
  **/
 typedef void (*EBookEListAsyncCallback)   (EBook *book, const GError *error, EList *list, gpointer closure);
 
+/**
+ * EBook:
+ *
+ * The deprecated API for accessing the addressbook
+ *
+ * Since: 2.32
+ *
+ * Deprecated: 3.2: Use #EBookClient instead 
+ */
 struct _EBook {
        GObject       parent;
        /*< private >*/
        EBookPrivate *priv;
 };
 
+/**
+ * EBookClass:
+ * @writable_status: deprecated
+ * @connection_status: deprecated
+ * @backend_died: deprecated
+ *
+ * Class structure for the deprecated API for accessing the addressbook
+ *
+ * Since: 2.32
+ *
+ * Deprecated: 3.2: Use #EBookClient instead 
+ */
 struct _EBookClass {
+       /*< private >*/
        GObjectClass parent;
 
+       /*< public >*/
        /*
         * Signals.
         */
@@ -141,6 +178,7 @@ struct _EBookClass {
        void (* connection_status) (EBook *book, gboolean connected);
        void (* backend_died)    (EBook *book);
 
+       /*< private >*/
        /* Padding for future expansion */
        void (*_ebook_reserved0) (void);
        void (*_ebook_reserved1) (void);
diff --git a/addressbook/libedata-book/e-book-backend-sqlitedb.c 
b/addressbook/libedata-book/e-book-backend-sqlitedb.c
index fb21912..1aa66c7 100644
--- a/addressbook/libedata-book/e-book-backend-sqlitedb.c
+++ b/addressbook/libedata-book/e-book-backend-sqlitedb.c
@@ -297,17 +297,6 @@ get_bool_cb (gpointer ref,
        return 0;
 }
 
-/**
- * e_book_sql_exec
- * @db:
- * @stmt:
- * @callback:
- * @data:
- * @error:
- *
- * Callers should hold the rw lock depending on read or write operation
- * Returns:
- **/
 static gboolean
 book_backend_sql_exec_real (sqlite3 *db,
                             const gchar *stmt,
@@ -1878,18 +1867,18 @@ e_book_backend_sqlitedb_new_full (const gchar *path,
 }
 
 /**
- * e_book_backend_sqlitedb_new
+ * e_book_backend_sqlitedb_new:
  * @path: location where the db would be created
  * @emailid: email id of the user
  * @folderid: folder id of the address-book
  * @folder_name: name of the address-book
  * @store_vcard: True if the vcard should be stored inside db, if FALSE only the summary fields would be 
stored inside db.
- * @error:
+ * @error: A location to store any error that may have occurred.
  *
  * If the path for multiple addressbooks are same, the contacts from all addressbooks
  * would be stored in same db in different tables.
  *
- * Returns:
+ * Returns: (transfer full): A reference to a #EBookBackendSqliteDB
  *
  * Since: 3.2
  **/
@@ -2470,13 +2459,13 @@ e_book_backend_sqlitedb_new_contacts (EBookBackendSqliteDB *ebsdb,
 }
 
 /**
- * e_book_backend_sqlitedb_add_contact
- * @ebsdb:
+ * e_book_backend_sqlitedb_add_contact:
+ * @ebsdb: An #EBookBackendSqliteDB
  * @folderid: folder id
  * @contact: EContact to be added
  * @partial_content: contact does not contain full information. Used when
  * the backend cache's partial information for auto-completion.
- * @error:
+ * @error: A location to store any error that may have occurred.
  *
  * This is a convenience wrapper for e_book_backend_sqlitedb_add_contacts,
  * which is the preferred means to add multiple contacts when possible.
@@ -4136,9 +4125,9 @@ book_backend_sqlitedb_search_full (EBookBackendSqliteDB *ebsdb,
 }
 
 /**
- * e_book_backend_sqlitedb_search 
- * @ebsdb: 
- * @folderid: 
+ * e_book_backend_sqlitedb_search:
+ * @ebsdb: An #EBookBackendSqliteDB
+ * @folderid: folder id of the address-book
  * @sexp: search expression; use NULL or an empty string to get all stored
  * contacts.
  * @fields_of_interest: a #GHashTable containing the names of fields to return,
@@ -4149,7 +4138,7 @@ book_backend_sqlitedb_search_full (EBookBackendSqliteDB *ebsdb,
  * for the provided query @sexp.
  * @with_all_required_fields: (allow none) (out): Whether all the required
  * fields are present in the returned vcards.
- * @error: 
+ * @error: A location to store any error that may have occurred
  *
  * Searching with summary fields is always supported. Search expressions
  * containing any other field is supported only if backend chooses to store
diff --git a/addressbook/libedata-book/e-book-backend.h b/addressbook/libedata-book/e-book-backend.h
index 43594cb..cd52fe9 100644
--- a/addressbook/libedata-book/e-book-backend.h
+++ b/addressbook/libedata-book/e-book-backend.h
@@ -100,14 +100,67 @@ typedef struct _EBookBackend EBookBackend;
 typedef struct _EBookBackendClass EBookBackendClass;
 typedef struct _EBookBackendPrivate EBookBackendPrivate;
 
+/**
+ * EBookBackend:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ */
 struct _EBookBackend {
+       /*< private >*/
        EBackend parent;
        EBookBackendPrivate *priv;
 };
 
+
+/**
+ * EBookBackendClass:
+ * @use_serial_dispatch_queue: Whether a serial dispatch queue should
+ *                             be used for this backend or not.
+ * @get_backend_property: Fetch a property value by name from the backend
+ * @open_sync: Open the backend
+ * @refresh_sync: Refresh the backend
+ * @create_contacts_sync: Add and store the passed vcards
+ * @modify_contacts_sync: Modify the existing contacts using the passed vcards
+ * @remove_contacts_sync: Remove the contacts specified by the passed UIDs
+ * @get_contact_sync: Fetch a contact by UID
+ * @get_contact_list_sync: Fetch a list of contacts based on a search expression
+ * @get_contact_list_uids_sync: Fetch a list of contact UIDs based on a search expression (optional)
+ * @start_view: Start up the specified view
+ * @stop_view: Stop the specified view
+ * @notify_update: Notify changes which might have occured for a given contact
+ * @get_direct_book: For addressbook backends which support Direct Read Access,
+ *                   report some information on how to access the addressbook persistance directly
+ * @configure_direct: For addressbook backends which support Direct Read Access, configure a
+ *                    backend instantiated on the client side for Direct Read Access, using data
+ *                    reported from the server via the @get_direct_book method.
+ * @sync: Sync the backend's persistance
+ * @set_locale: Store & remember the passed locale setting
+ * @dup_locale: Return the currently set locale setting (must be a string duplicate, for thread safety).
+ * @create_cursor: Create an #EDataBookCursor
+ * @delete_cursor: Delete an #EDataBookCursor previously created by this backend
+ * @closed: A signal notifying that the backend was closed
+ * @shutdown: A signal notifying that the backend is being shut down
+ * @open: Deprecated method
+ * @refresh: Deprecated method
+ * @create_contacts: Deprecated method
+ * @remove_contacts: Deprecated method
+ * @modify_contacts: Deprecated method
+ * @get_contact: Deprecated method
+ * @get_contact_list: Deprecated method
+ * @get_contact_list_uids: Deprecated method
+ *
+ * Class structure for the #EBookBackend class.
+ *
+ * These virtual methods must be implemented when writing
+ * an addressbook backend.
+ */
 struct _EBookBackendClass {
+       /*< private >*/
        EBackendClass parent_class;
 
+       /*< public >*/
+
        /* Set this to TRUE to use a serial dispatch queue, instead
         * of a concurrent dispatch queue.  A serial dispatch queue
         * executes one method at a time in the order in which they
diff --git a/calendar/libecal/e-cal-client-view.c b/calendar/libecal/e-cal-client-view.c
index e37f15b..447ba37 100644
--- a/calendar/libecal/e-cal-client-view.c
+++ b/calendar/libecal/e-cal-client-view.c
@@ -740,18 +740,28 @@ e_cal_client_view_class_init (ECalClientViewClass *class)
        object_class->dispose = cal_client_view_dispose;
        object_class->finalize = cal_client_view_finalize;
 
+       /**
+        * ECalClientView:client:
+        *
+        * The ECalClient for the view
+        */
        g_object_class_install_property (
                object_class,
                PROP_CLIENT,
                g_param_spec_object (
                        "client",
+                       "Client",
                        "The ECalClient for the view",
-                       NULL,
                        E_TYPE_CAL_CLIENT,
                        G_PARAM_READWRITE |
                        G_PARAM_CONSTRUCT_ONLY |
                        G_PARAM_STATIC_STRINGS));
 
+       /**
+        * ECalClientView:connection:
+        *
+        * The GDBusConnection used to create the D-Bus proxy
+        */
        g_object_class_install_property (
                object_class,
                PROP_CONNECTION,
@@ -765,6 +775,11 @@ e_cal_client_view_class_init (ECalClientViewClass *class)
                        G_PARAM_CONSTRUCT_ONLY |
                        G_PARAM_STATIC_STRINGS));
 
+       /**
+        * ECalClientView:object-path:
+        *
+        * The object path used to create the D-Bus proxy
+        */
        g_object_class_install_property (
                object_class,
                PROP_OBJECT_PATH,
diff --git a/calendar/libecal/e-cal-client.h b/calendar/libecal/e-cal-client.h
index 4e70633..abfbc86 100644
--- a/calendar/libecal/e-cal-client.h
+++ b/calendar/libecal/e-cal-client.h
@@ -508,13 +508,13 @@ gboolean  e_cal_client_add_timezone_sync  (ECalClient *client,
                                                 GCancellable *cancellable,
                                                 GError **error);
 
-#ifndef E_CAL_DISABLE_DEPRECATED
+#ifndef EDS_DISABLE_DEPRECATED
 ECalClient *   e_cal_client_new                (ESource *source,
                                                 ECalClientSourceType source_type,
                                                 GError **error);
 GError *       e_cal_client_error_create       (ECalClientError code,
                                                 const gchar *custom_msg);
-#endif /* E_CAL_DISABLE_DEPRECATED */
+#endif /* EDS_DISABLE_DEPRECATED */
 
 G_END_DECLS
 
diff --git a/calendar/libecal/e-cal-component.c b/calendar/libecal/e-cal-component.c
index 538488c..c87c092 100644
--- a/calendar/libecal/e-cal-component.c
+++ b/calendar/libecal/e-cal-component.c
@@ -3238,9 +3238,10 @@ e_cal_component_get_exrule_list (ECalComponent *comp,
  * e_cal_component_get_exrule_property_list:
  * @comp: A calendar component object.
  * @recur_list: (out) (transfer none) (element-type icalrecurrencetype):
- * Returns a list of exception rule properties
  *
  * Queries the list of exception rule properties of a calendar component object.
+ *
+ * Returns: a list of exception rule properties
  **/
 void
 e_cal_component_get_exrule_property_list (ECalComponent *comp,
diff --git a/calendar/libecal/e-cal-system-timezone.c b/calendar/libecal/e-cal-system-timezone.c
index 8015428..fe96726 100644
--- a/calendar/libecal/e-cal-system-timezone.c
+++ b/calendar/libecal/e-cal-system-timezone.c
@@ -919,12 +919,15 @@ system_timezone_win32_query_registry (void)
 /**
  * e_cal_system_timezone_get_location:
  *
- * Returns system timezone location string, NULL on an error.
- * Returned pointer should be freed with g_free().
+ * Fetches the system timezone location string.
  *
  * Note: Since 3.4 the returned timezone location is either NULL or
  * an equivalent within known libical timezones.
  *
+ * The returned string should be freed with g_free().
+ *
+ * Returns: (transfer full): system timezone location string, or %NULL on an error.
+ *
  * Since: 2.28
  **/
 gchar *
diff --git a/calendar/libecal/e-cal-util.c b/calendar/libecal/e-cal-util.c
index 36b3dcc..03cbb01 100644
--- a/calendar/libecal/e-cal-util.c
+++ b/calendar/libecal/e-cal-util.c
@@ -1182,8 +1182,9 @@ e_cal_util_remove_instances (icalcomponent *icalcomp,
 /**
  * e_cal_util_get_system_timezone_location:
  *
- * Returns system timezone location string, NULL on an error.
- * Returned pointer should be freed with g_free().
+ * Fetches system timezone localtion string.
+ *
+ * Returns: (transfer full): system timezone location string, %NULL on an error.
  *
  * Since: 2.28
  **/
@@ -1196,8 +1197,11 @@ e_cal_util_get_system_timezone_location (void)
 /**
  * e_cal_util_get_system_timezone:
  *
- * Returns icaltimezone object of the system timezone. NULL on an error.
- * Returned pointer is part of the built-in timezones, thus do not free it.
+ * Fetches system timezone icaltimezone object.
+ *
+ * The returned pointer is part of the built-in timezones and should not be freed.
+ *
+ * Returns: (transfer none): The icaltimezone object of the system timezone, or %NULL on an error.
  *
  * Since: 2.28
  **/
@@ -1243,12 +1247,12 @@ componenttime_to_utc_timet (const ECalComponentDateTime *dt_time,
 /**
  * e_cal_util_get_component_occur_times:
  * @comp: an #ECalComponent
- * @start: (out):
- * @end: (out):
- * @tz_cb: (closure tz_cb_data) (scope call):
- * @tz_cb_data: (closure):
- * @default_timezone:
- * @kind:
+ * @start: (out): Location to store the start time
+ * @end: (out): Location to store the end time
+ * @tz_cb: (closure tz_cb_data) (scope call): The #ECalRecurResolveTimezoneFn to call
+ * @tz_cb_data: (closure): User data to be passed to the @tz_cb callback
+ * @default_timezone: The default timezone
+ * @kind: the type of component, indicated with an icalcomponent_kind
  *
  * Find out when the component starts and stops, being careful about
  * recurrences.
diff --git a/calendar/libedata-cal/e-cal-backend-intervaltree.c 
b/calendar/libedata-cal/e-cal-backend-intervaltree.c
index 8ef66e5..3564441 100644
--- a/calendar/libedata-cal/e-cal-backend-intervaltree.c
+++ b/calendar/libedata-cal/e-cal-backend-intervaltree.c
@@ -662,7 +662,7 @@ e_intervaltree_remove (EIntervalTree *tree,
  * @start: start of the interval
  * @end: end of the interval
  * 
- * Returns list of nodes that overlaps given interval or %NULL.
+ * Returns: list of nodes that overlaps given interval or %NULL.
  *
  * Since: 2.32
  **/
diff --git a/calendar/libedata-cal/e-cal-backend-store.c b/calendar/libedata-cal/e-cal-backend-store.c
index 5296713..7389878 100644
--- a/calendar/libedata-cal/e-cal-backend-store.c
+++ b/calendar/libedata-cal/e-cal-backend-store.c
@@ -988,18 +988,28 @@ e_cal_backend_store_class_init (ECalBackendStoreClass *class)
        class->get_components = cal_backend_store_get_components;
        class->get_component_ids = cal_backend_store_get_component_ids;
 
+       /**
+        * ECalBackendStore:path:
+        *
+        * The directory to store the file.
+        */
        g_object_class_install_property (
                object_class,
                PROP_PATH,
                g_param_spec_string (
                        "path",
-                       NULL,
-                       NULL,
+                       "Path",
+                       "The directory to store the file",
                        NULL,
                        G_PARAM_READWRITE |
                        G_PARAM_CONSTRUCT_ONLY |
                        G_PARAM_STATIC_STRINGS));
 
+       /**
+        * ECalBackendStore:timezone-cache:
+        *
+        * An object implementing the ETimezoneCache interface.
+        */
        g_object_class_install_property (
                object_class,
                PROP_TIMEZONE_CACHE,
@@ -1385,8 +1395,8 @@ e_cal_backend_store_get_components (ECalBackendStore *store)
 /**
  * e_cal_backend_store_get_components_occuring_in_range:
  * @store: An #ECalBackendStore object.
- * @start:
- * @end:
+ * @start: Start time
+ * @end: End time
  *
  * Retrieves a list of components stored in the store, that are occuring
  * in time range [start, end].
diff --git a/libebackend/e-authentication-mediator.h b/libebackend/e-authentication-mediator.h
index f4c5e9c..809ae48 100644
--- a/libebackend/e-authentication-mediator.h
+++ b/libebackend/e-authentication-mediator.h
@@ -59,11 +59,20 @@ typedef struct _EAuthenticationMediatorPrivate EAuthenticationMediatorPrivate;
  * Since: 3.6
  **/
 struct _EAuthenticationMediator {
+       /*< private >*/
        GObject parent;
        EAuthenticationMediatorPrivate *priv;
 };
 
+/**
+ * EAuthenticationMediatorClass:
+ *
+ * Class structure for the #EAuthenticationMediator object
+ *
+ * Since: 3.6
+ */
 struct _EAuthenticationMediatorClass {
+       /*< private >*/
        GObjectClass parent_class;
 };
 
diff --git a/libebackend/e-authentication-session.h b/libebackend/e-authentication-session.h
index eea00c2..4dc1349 100644
--- a/libebackend/e-authentication-session.h
+++ b/libebackend/e-authentication-session.h
@@ -65,13 +65,27 @@ typedef struct _EAuthenticationSessionPrivate EAuthenticationSessionPrivate;
  * Since: 3.6
  **/
 struct _EAuthenticationSession {
+       /*< private >*/
        GObject parent;
        EAuthenticationSessionPrivate *priv;
 };
 
+/**
+ * EAuthenticationSessionClass:
+ * @execute_sync: Authenticate synchronously
+ * @execute: Initiate authentication
+ * @execute_finish: Complete authentication
+ *
+ * Class structure for the #EAuthenticationSession object
+ *
+ * Since: 3.6
+ */
 struct _EAuthenticationSessionClass {
+       /*< private >*/
        GObjectClass parent_class;
 
+       /*< public >*/
+
        /* Methods */
        EAuthenticationSessionResult
                        (*execute_sync) (EAuthenticationSession *session,
@@ -88,6 +102,7 @@ struct _EAuthenticationSessionClass {
                                         GAsyncResult *result,
                                         GError **error);
 
+       /*< private >*/
        /* Reserved slots. */
        gpointer reserved[16];
 };
diff --git a/libebackend/e-backend-factory.h b/libebackend/e-backend-factory.h
index 88c556e..9b74fff 100644
--- a/libebackend/e-backend-factory.h
+++ b/libebackend/e-backend-factory.h
@@ -60,18 +60,31 @@ typedef struct _EBackendFactoryPrivate EBackendFactoryPrivate;
  * Since: 3.4
  **/
 struct _EBackendFactory {
+       /*< private >*/
        EExtension parent;
        EBackendFactoryPrivate *priv;
 };
 
+/**
+ * EBackendFactoryClass:
+ * @get_hash_key: Get the hash key for this factory
+ * @new_backend: Create a new #EBackend of the appropriate type for the passed #ESource
+ *
+ * Base class structure for the #EBackendFactory class
+ *
+ * Since: 3.4
+ **/
 struct _EBackendFactoryClass {
+       /*< private >*/
        EExtensionClass parent_class;
 
+       /*< public >*/
        /* Methods */
        const gchar *   (*get_hash_key)         (EBackendFactory *factory);
        EBackend *      (*new_backend)          (EBackendFactory *factory,
                                                 ESource *source);
 
+       /*< private >*/
        gpointer reserved[16];
 };
 
diff --git a/libebackend/e-backend.c b/libebackend/e-backend.c
index 2abbf1e..6d8a96f 100644
--- a/libebackend/e-backend.c
+++ b/libebackend/e-backend.c
@@ -859,9 +859,10 @@ e_backend_authenticate_finish (EBackend *backend,
  * @backend: an #EBackend
  *
  * Gets an instance of #EUserPrompter, associated with this @backend.
- * The instance is owned by the @backend.
  *
- * Returns: (transfer-none): an #EUserPrompter instance
+ * The returned instance is owned by the @backend.
+ *
+ * Returns: (transfer none): an #EUserPrompter instance
  *
  * Since: 3.8
  **/
diff --git a/libebackend/e-backend.h b/libebackend/e-backend.h
index 74e7e8d..e2933b8 100644
--- a/libebackend/e-backend.h
+++ b/libebackend/e-backend.h
@@ -62,13 +62,27 @@ typedef struct _EBackendPrivate EBackendPrivate;
  * Since: 3.4
  **/
 struct _EBackend {
+       /*< private >*/
        GObject parent;
        EBackendPrivate *priv;
 };
 
+/**
+ * EBackendClass:
+ * @authenticate_sync: Authenticate synchronously
+ * @authenticate: Initiate authentication
+ * @authenticate_finish: Complete authentication
+ * @get_destination_address: Fetch the destination address
+ *
+ * Base class structure for the #EBackend class
+ *
+ * Since: 3.4
+ **/
 struct _EBackendClass {
+       /*< private >*/
        GObjectClass parent_class;
 
+       /*< public >*/
        /* Methods */
        gboolean        (*authenticate_sync)    (EBackend *backend,
                                                 ESourceAuthenticator *auth,
@@ -88,6 +102,7 @@ struct _EBackendClass {
                                                 gchar **host,
                                                 guint16 *port);
 
+       /*< private >*/
        gpointer reserved[12];
 };
 
diff --git a/libedataserver/e-cancellable-locks.c b/libedataserver/e-cancellable-locks.c
index fe0f2d6..312d68a 100644
--- a/libedataserver/e-cancellable-locks.c
+++ b/libedataserver/e-cancellable-locks.c
@@ -24,7 +24,7 @@
 #include "e-cancellable-locks.h"
 
 /**
- * SECTION:cancellable_locks
+ * SECTION:e-cancellable-locks
  * @title: Cancellable Locks
  * @short_description: locks, which can listen for a #GCancellable during lock call
  *
diff --git a/libedataserver/e-client.c b/libedataserver/e-client.c
index 4308f08..84ede92 100644
--- a/libedataserver/e-client.c
+++ b/libedataserver/e-client.c
@@ -781,16 +781,27 @@ e_client_class_init (EClientClass *class)
        class->refresh = client_refresh;
        class->refresh_finish = client_refresh_finish;
 
+       /**
+        * EClient:capabilities:
+        *
+        * The capabilities of this client
+        */
        g_object_class_install_property (
                object_class,
                PROP_CAPABILITIES,
                g_param_spec_pointer (
                        "capabilities",
-                       NULL,
-                       NULL,
+                       "Capabilities",
+                       "The capabilities of this client",
                        G_PARAM_READABLE |
                        G_PARAM_STATIC_STRINGS));
 
+       /**
+        * EClient:main-context:
+        *
+        * The main loop context in which notifications for
+        * this client will be delivered.
+        */
        g_object_class_install_property (
                object_class,
                PROP_MAIN_CONTEXT,
@@ -803,46 +814,70 @@ e_client_class_init (EClientClass *class)
                        G_PARAM_READABLE |
                        G_PARAM_STATIC_STRINGS));
 
+       /**
+        * EClient:online:
+        *
+        * Whether this client's backing data is online.
+        */
        g_object_class_install_property (
                object_class,
                PROP_ONLINE,
                g_param_spec_boolean (
                        "online",
-                       NULL,
-                       NULL,
+                       "Online",
+                       "Whether this client is online",
                        FALSE,
                        G_PARAM_READWRITE |
                        G_PARAM_STATIC_STRINGS));
 
+       /**
+        * EClient:opened:
+        *
+        * Whether this client is open and ready to use.
+        *
+        * Deprecated: 3.8: This property is no longer relevant and
+        * will always be %TRUE after successfully creating any concrete
+        * type of #EClient.
+        */
        g_object_class_install_property (
                object_class,
                PROP_OPENED,
                g_param_spec_boolean (
                        "opened",
-                       NULL,
-                       NULL,
+                       "Opened",
+                       "Whether this client is open and ready to use",
                        FALSE,
                        G_PARAM_READABLE |
                        G_PARAM_STATIC_STRINGS));
 
+       /**
+        * EClient:readonly:
+        *
+        * Whether this client's backing data is readonly.
+        */
        g_object_class_install_property (
                object_class,
                PROP_READONLY,
                g_param_spec_boolean (
                        "readonly",
-                       NULL,
-                       NULL,
+                       "Read only",
+                       "Whether this client's backing data is readonly",
                        FALSE,
                        G_PARAM_READABLE |
                        G_PARAM_STATIC_STRINGS));
 
+       /**
+        * EClient:source:
+        *
+        * The #ESource for which this client was created.
+        */
        g_object_class_install_property (
                object_class,
                PROP_SOURCE,
                g_param_spec_object (
                        "source",
-                       NULL,
-                       NULL,
+                       "Source",
+                       "The ESource for which this client was created",
                        E_TYPE_SOURCE,
                        G_PARAM_READWRITE |
                        G_PARAM_CONSTRUCT_ONLY |
diff --git a/libedataserver/e-operation-pool.c b/libedataserver/e-operation-pool.c
index 3672271..a85fd94 100644
--- a/libedataserver/e-operation-pool.c
+++ b/libedataserver/e-operation-pool.c
@@ -31,9 +31,9 @@ struct _EOperationPool {
 
 /**
  * e_operation_pool_new: (skip)
- * @max_threads:
- * @thread_func:
- * @user_data:
+ * @max_threads: Maximum number of threads for this pool
+ * @thread_func: Function to run for a given thread
+ * @user_data: The user data to pass to @thread_func
  *
  * FIXME: Document me.
  *
diff --git a/libedataserver/e-sexp.c b/libedataserver/e-sexp.c
index bbf898d..8b4510d 100644
--- a/libedataserver/e-sexp.c
+++ b/libedataserver/e-sexp.c
@@ -1742,8 +1742,8 @@ e_sexp_evaluate_occur_times (ESExp *f,
 
 /**
  * e_sexp_encode_bool:
- * @s:
- * @state:
+ * @s: A #GString to append to
+ * @state: The boolean value
  *
  * Encode a bool into an s-expression @s.  Bools are
  * encoded using #t #f syntax.
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]