Correct and enhance developer documentation a bit

9 files changed, 99 insertions, 16 deletions

diff --git a/addressbook/libebook-contacts/e-book-contacts-types.c b/addressbook/libebook-contacts/e-book-contacts-types.c
index 7356f07b8..bf04dcf00 100644
--- a/addressbook/libebook-contacts/e-book-contacts-types.c
+++ b/addressbook/libebook-contacts/e-book-contacts-types.c
@@ -26,7 +26,9 @@ G_DEFINE_QUARK (e-book-client-error-quark, e_book_client_error)
  * e_book_client_error_to_string:
  * @code: an #EBookClientError code
  *
- * FIXME: Document me.
+ * Get localized human readable description of the given error code.
+ *
+ * Returns: Localized human readable description of the given error code
  *
  * Since: 3.2
  **/
diff --git a/addressbook/libebook/e-book.c b/addressbook/libebook/e-book.c
index a54e2de16..1412b63c9 100644
--- a/addressbook/libebook/e-book.c
+++ b/addressbook/libebook/e-book.c
@@ -2100,6 +2100,8 @@ e_book_cancel (EBook *book,
  * Similar to above e_book_cancel function, only cancels last, still running,
  * asynchronous operation.
  *
+ * Returns: %TRUE on success, %FALSE otherwise
+ *
  * Since: 2.24
  *
  * Deprecated: 3.2: Use e_client_cancel_all() or e_client_cancel_op() on an
diff --git a/addressbook/libedata-book/e-book-backend-db-cache.c b/addressbook/libedata-book/e-book-backend-db-cache.c
index 6d074fabe..0081d0b69 100644
--- a/addressbook/libedata-book/e-book-backend-db-cache.c
+++ b/addressbook/libedata-book/e-book-backend-db-cache.c
@@ -97,7 +97,10 @@ e_book_backend_db_cache_set_filename (DB *db,
  * e_book_backend_db_cache_get_filename:
  * @db:  DB Handle
  *
- * Get the filename for db cacahe file.
+ * Get the filename for db cache file.
+ *
+ * Returns: The filename for db cache file. Free with g_free()
+ *   when done with it.
  *
  * Deprecated: 3.12: Use #EBookSqlite instead
  **/
diff --git a/addressbook/libedata-book/e-book-backend-sqlitedb.c b/addressbook/libedata-book/e-book-backend-sqlitedb.c
index 6c85dadbc..f6d2d0529 100644
--- a/addressbook/libedata-book/e-book-backend-sqlitedb.c
+++ b/addressbook/libedata-book/e-book-backend-sqlitedb.c
@@ -2849,6 +2849,8 @@ uid_rev_fields (GHashTable *fields_of_interest)
  * This only checks if all the fields are part of the default summary fields,
  * not part of the configured summary fields.
  *
+ * Returns: Whether all @fields_of_interest are part of the default summary fields
+ *
  * Since: 3.2
  *
  * Deprecated: 3.8: Use #EBookSqlite instead
diff --git a/addressbook/libedata-book/e-book-backend.c b/addressbook/libedata-book/e-book-backend.c
index 51cc2f4e3..962889f6c 100644
--- a/addressbook/libedata-book/e-book-backend.c
+++ b/addressbook/libedata-book/e-book-backend.c
@@ -3338,6 +3338,9 @@ e_book_backend_set_locale (EBookBackend *backend,
  *
  * Fetches a copy of the currently configured locale for the addressbook
  *
+ * Returns: A copy of the currently configured locale for the addressbook.
+ *   Free with g_free() when done with it.
+ *
  * Since: 3.12
  */
 gchar *
diff --git a/addressbook/libedata-book/e-book-sqlite.c b/addressbook/libedata-book/e-book-sqlite.c
index bc9d6b0d1..0e9ea83fe 100644
--- a/addressbook/libedata-book/e-book-sqlite.c
+++ b/addressbook/libedata-book/e-book-sqlite.c
@@ -6538,6 +6538,7 @@ ebsql_new_default (const gchar *path,
 /**
  * e_book_sqlite_new:
  * @path: location to load or create the new database
+ * @source: an optional #ESource, associated with the #EBookSqlite, or %NULL
  * @cancellable: (allow-none): A #GCancellable
  * @error: (allow-none): A location to store any error that may have occurred.
  *
@@ -6576,6 +6577,7 @@ e_book_sqlite_new (const gchar *path,
 /**
  * e_book_sqlite_new_full:
  * @path: location to load or create the new database
+ * @source: an optional #ESource, associated with the #EBookSqlite, or %NULL
  * @setup: (allow-none): an #ESourceBackendSummarySetup describing how the summary should be setup, or %NULL to use the default
  * @vcard_callback: (allow-none) (scope async) (closure user_data): A function to resolve vcards
  * @change_callback: (allow-none) (scope async) (closure user_data): A function to catch notifications of vcard changes
@@ -6865,7 +6867,7 @@ e_book_sqlite_ref_collator (EBookSqlite *ebsql)
  * use g_object_unref() when finished using the source.
  * It can be %NULL in some cases, like when running tests.
  *
- * Returns: (transfer-full): A reference to the #ESource to which @ebsql
+ * Returns: (transfer full): A reference to the #ESource to which @ebsql
  * is paired, or %NULL.
  *
  * Since: 3.16
diff --git a/addressbook/libedata-book/e-data-book.c b/addressbook/libedata-book/e-data-book.c
index f4c35fef5..9c17cb74c 100644
--- a/addressbook/libedata-book/e-data-book.c
+++ b/addressbook/libedata-book/e-data-book.c
@@ -361,6 +361,11 @@ data_book_convert_to_client_error (GError *error)
 
 /**
  * e_data_book_status_to_string:
+ * @status: an #EDataBookStatus
+ *
+ * Get localized human readable description of the given status code.
+ *
+ * Returns: Localized human readable description of the given status code
  *
  * Since: 2.32
  **/
@@ -477,10 +482,17 @@ e_data_book_create_error (EDataBookStatus status,
 
 /**
  * e_data_book_create_error_fmt:
+ * @status: an #EDataBookStatus
+ * @custom_msg_fmt: Custom message to use for the error. When NULL,
+ *   then uses a default message based on the @status code.
+ * @...: arguments for the @custom_msg_fmt
  *
  * Similar as e_data_book_create_error(), only here, instead of custom_msg,
  * is used a printf() format to create a custom_msg for the error.
  *
+ * Returns: (transfer full): a new #GError populated with the values
+ *   from the parameters.
+ *
  * Since: 2.32
  **/
 GError *
@@ -508,10 +520,13 @@ e_data_book_create_error_fmt (EDataBookStatus status,
 
 /**
  * e_data_book_string_slist_to_comma_string:
+ * @strings: (element-type gchar *): a list of gchar *
  *
  * Takes a list of strings and converts it to a comma-separated string of
  * values; free returned pointer with g_free()
  *
+ * Returns: (transfer full): comma-separated newly allocated text of @strings
+ *
  * Since: 3.2
  **/
 gchar *
@@ -1377,6 +1392,14 @@ data_book_handle_close_cb (EDBusAddressBook *dbus_interface,
 	return TRUE;
 }
 
+/**
+ * e_data_book_respond_open:
+ * @book: An #EDataBook
+ * @opid: An operation ID
+ * @error: Operation error, if any, automatically freed if passed it
+ *
+ * Notifies listeners of the completion of the open method call.
+ **/
 void
 e_data_book_respond_open (EDataBook *book,
                           guint opid,
@@ -1407,8 +1430,9 @@ e_data_book_respond_open (EDataBook *book,
 
 /**
  * e_data_book_respond_refresh:
- * @book: An addressbook client interface.
- * @error: Operation error, if any, automatically freed if passed it.
+ * @book: An #EDataBook
+ * @opid: An operation ID
+ * @error: Operation error, if any, automatically freed if passed it
  *
  * Notifies listeners of the completion of the refresh method call.
  *
@@ -1442,6 +1466,14 @@ e_data_book_respond_refresh (EDataBook *book,
 	g_object_unref (backend);
 }
 
+/**
+ * e_data_book_respond_get_contact:
+ * @book: An #EDataBook
+ * @opid: An operation ID
+ * @error: Operation error, if any, automatically freed if passed it
+ *
+ * Notifies listeners of the completion of the get_contact method call.
+ */
 void
 e_data_book_respond_get_contact (EDataBook *book,
                                  guint32 opid,
@@ -1480,6 +1512,17 @@ e_data_book_respond_get_contact (EDataBook *book,
 	g_object_unref (backend);
 }
 
+/**
+ * e_data_book_respond_get_contact_list:
+ * @book: An #EDataBook
+ * @opid: An operation ID
+ * @error: Operation error, if any, automatically freed if passed it
+ * @cards: (allow-none) (element-type gchar *): A list of vCard strings, or %NULL on error
+ *
+ * Finishes a call to get list of vCards which satisfy certain criteria.
+ *
+ * Since: 3.2
+ **/
 void
 e_data_book_respond_get_contact_list (EDataBook *book,
                                       guint32 opid,
@@ -1527,8 +1570,12 @@ e_data_book_respond_get_contact_list (EDataBook *book,
 
 /**
  * e_data_book_respond_get_contact_list_uids:
+ * @book: An #EDataBook
+ * @opid: An operation ID
+ * @error: Operation error, if any, automatically freed if passed it
+ * @uids: (allow-none) (element-type gchar *): A list of picked UIDs, or %NULL on error
  *
- * FIXME: Document me.
+ * Finishes a call to get list of UIDs which satisfy certain criteria.
  *
  * Since: 3.2
  **/
@@ -1574,8 +1621,12 @@ e_data_book_respond_get_contact_list_uids (EDataBook *book,
 
 /**
  * e_data_book_respond_create_contacts:
+ * @book: An #EDataBook
+ * @opid: An operation ID
+ * @error: Operation error, if any, automatically freed if passed it
+ * @contacts: (allow-none) (element-type EContact): A list of created #EContact-s, or %NULL on error
  *
- * FIXME: Document me!
+ * Finishes a call to create a list contacts.
  *
  * Since: 3.4
  **/
@@ -1623,8 +1674,12 @@ e_data_book_respond_create_contacts (EDataBook *book,
 
 /**
  * e_data_book_respond_modify_contacts:
+ * @book: An #EDataBook
+ * @opid: An operation ID
+ * @error: Operation error, if any, automatically freed if passed it
+ * @contacts: (allow-none) (element-type EContact): A list of modified #EContact-s, or %NULL on error
  *
- * FIXME: Document me!
+ * Finishes a call to modify a list of contacts.
  *
  * Since: 3.4
  **/
@@ -1670,6 +1725,17 @@ e_data_book_respond_modify_contacts (EDataBook *book,
 	g_object_unref (backend);
 }
 
+/**
+ * e_data_book_respond_remove_contacts:
+ * @book: An #EDataBook
+ * @opid: An operation ID
+ * @error: Operation error, if any, automatically freed if passed it
+ * @ids: (allow-none) (element-type gchar *): A list of removed contact UID-s, or %NULL on error
+ *
+ * Finishes a call to remove a list of contacts.
+ *
+ * Since: 3.4
+ **/
 void
 e_data_book_respond_remove_contacts (EDataBook *book,
                                      guint32 opid,
@@ -1712,8 +1778,10 @@ e_data_book_respond_remove_contacts (EDataBook *book,
 
 /**
  * e_data_book_report_error:
+ * @book: An #EDataBook
+ * @message: An error message
  *
- * FIXME: Document me.
+ * Notifies the clients about an error, which happened out of any client-initiate operation.
  *
  * Since: 3.2
  **/
@@ -1729,8 +1797,11 @@ e_data_book_report_error (EDataBook *book,
 
 /**
  * e_data_book_report_backend_property_changed:
+ * @book: An #EDataBook
+ * @prop_name: Property name which changed
+ * @prop_value: The new property value
  *
- * FIXME: Document me.
+ * Notifies the clients about a property change.
  *
  * Since: 3.2
  **/
diff --git a/addressbook/libedata-book/e-data-book.h b/addressbook/libedata-book/e-data-book.h
index 2e2f7ab4d..48e8a0bad 100644
--- a/addressbook/libedata-book/e-data-book.h
+++ b/addressbook/libedata-book/e-data-book.h
@@ -52,11 +52,13 @@ typedef struct _EDataBookClass EDataBookClass;
 typedef struct _EDataBookPrivate EDataBookPrivate;
 
 struct _EDataBook {
+	/*< private >*/
 	GObject parent;
 	EDataBookPrivate *priv;
 };
 
 struct _EDataBookClass {
+	/*< private >*/
 	GObjectClass parent_class;
 };
 
diff --git a/addressbook/libedata-book/e-subprocess-book-factory.c b/addressbook/libedata-book/e-subprocess-book-factory.c
index a1868bbe7..bef12d6f0 100644
--- a/addressbook/libedata-book/e-subprocess-book-factory.c
+++ b/addressbook/libedata-book/e-subprocess-book-factory.c
@@ -17,15 +17,11 @@
  * Authors: Fabiano Fidêncio <fidencio@redhat.com>
  */
 
-/**
- * SECTION: e-subprocess-book-factory
- * @include: libedata-book/libedata-book.h
- * @short_description: Responsible for #EBackend objects
- *
+/*
  * This class handles and creates #EBackend objects from inside
  * their own subprocesses and also serves as the layer that does
  * the communication between #EDataBookFactory and #EBackend
- **/
+ */
 
 #ifdef HAVE_CONFIG_H
 #include <config.h>