[evolution-data-server] Fix some of the gtk-doc warnings in Camel
- From: Milan Crha <mcrha src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [evolution-data-server] Fix some of the gtk-doc warnings in Camel
- Date: Fri, 2 Dec 2016 12:57:54 +0000 (UTC)
commit 93e0eb03dfd755dc009b0ab9b6d425bfd879d346
Author: Milan Crha <mcrha redhat com>
Date: Fri Dec 2 13:57:40 2016 +0100
Fix some of the gtk-doc warnings in Camel
src/camel/camel-folder-search.c | 26 ++++++----
src/camel/camel-folder-summary.c | 55 ++++++++++++++++++-
src/camel/camel-folder-thread.c | 13 +++--
src/camel/camel-folder.c | 14 ++++-
src/camel/camel-folder.h | 8 +++
src/camel/camel-gpg-context.c | 2 +-
src/camel/camel-html-parser.c | 12 +++-
src/camel/camel-index.c | 33 ++++++++---
src/camel/camel-lock.c | 31 ++++++++---
src/camel/camel-mempool.c | 4 +-
src/camel/camel-message-info.c | 3 +-
src/camel/camel-mime-filter.c | 2 +-
src/camel/camel-mime-message.c | 4 +-
src/camel/camel-mime-part-utils.c | 17 ++++--
src/camel/camel-mime-utils.c | 8 ++-
src/camel/camel-msgport.c | 10 ++++
src/camel/camel-net-utils.c | 17 ++++++-
src/camel/camel-nntp-address.c | 2 +-
src/camel/camel-object.h | 1 +
src/camel/camel-offline-store.c | 8 +++
src/camel/camel-sasl-gssapi.c | 1 +
src/camel/camel-search-sql-sexp.c | 33 +++++++----
src/camel/camel-service.h | 5 ++
src/camel/camel-session.c | 11 ++++-
src/camel/camel-sexp.c | 105 ++++++++++++++++++++++++++++++++-----
src/camel/camel-sexp.h | 26 +++++++--
src/camel/camel-utf8.c | 6 +-
src/camel/camel-vee-folder.c | 2 +-
src/camel/camel-vee-store.c | 66 ++++++++++++++---------
29 files changed, 406 insertions(+), 119 deletions(-)
---
diff --git a/src/camel/camel-folder-search.c b/src/camel/camel-folder-search.c
index 850d27d..c16e317 100644
--- a/src/camel/camel-folder-search.c
+++ b/src/camel/camel-folder-search.c
@@ -1725,7 +1725,7 @@ camel_folder_search_init (CamelFolderSearch *search)
* Particular methods may be overriden by an implementation to
* implement a search for any sort of backend.
*
- * Returns: A new CamelFolderSearch widget.
+ * Returns: (transfer full): A new CamelFolderSearch intstance.
**/
CamelFolderSearch *
camel_folder_search_new (void)
@@ -1905,8 +1905,8 @@ camel_folder_search_get_summary_empty (CamelFolderSearch *search)
/**
* camel_folder_search_set_body_index:
- * @search:
- * @body_index:
+ * @search: a #CamelFolderSearch
+ * @body_index: (nullable): a #CamelIndex
*
* Set the index representing the contents of all messages
* in this folder. If this is not set, then the folder implementation
@@ -1982,8 +1982,8 @@ free_pstring_array (GPtrArray *array)
/**
* camel_folder_search_count:
- * @search:
- * @expr:
+ * @search: a #CamelFolderSearch
+ * @expr: a search expression to run
* @cancellable: a #GCancellable
* @error: return location for a #GError, or %NULL
*
@@ -2144,8 +2144,8 @@ fail:
/**
* camel_folder_search_search:
- * @search:
- * @expr:
+ * @search: a #CamelFolderSearch
+ * @expr: a search expression to run
* @uids: (element-type utf8): to search against, NULL for all uid's.
* @cancellable: a #GCancellable
* @error: return location for a #GError, or %NULL
@@ -2153,7 +2153,9 @@ fail:
* Run a search. Search must have had Folder already set on it, and
* it must implement summaries.
*
- * Returns: (element-type utf8) (transfer full):
+ * Returns: (element-type utf8) (transfer full): a #GPtrArray with matching UIDs,
+ * or %NULL on error. Use camel_folder_search_free_result() to free it when
+ * no longer needed.
**/
GPtrArray *
camel_folder_search_search (CamelFolderSearch *search,
@@ -2327,13 +2329,17 @@ fail:
/**
* camel_folder_search_free_result:
- * @result: (element-type utf8):
+ * @search: a #CamelFolderSearch
+ * @result: (element-type utf8) (nullable): a result to free
+ *
+ * Frees result of camel_folder_search_search() call.
**/
void
camel_folder_search_free_result (CamelFolderSearch *search,
GPtrArray *result)
{
- free_pstring_array (result);
+ if (result)
+ free_pstring_array (result);
}
/**
diff --git a/src/camel/camel-folder-summary.c b/src/camel/camel-folder-summary.c
index f22d143..5d76801 100644
--- a/src/camel/camel-folder-summary.c
+++ b/src/camel/camel-folder-summary.c
@@ -1259,8 +1259,13 @@ camel_folder_summary_get_hash (CamelFolderSummary *summary)
/**
* camel_folder_summary_peek_loaded:
+ * @summary: a #CamelFolderSummary
+ * @uid: a message UID to look for
+ *
+ * Returns: (nullable) (transfer full): a #CamelMessageInfo for the given @uid,
+ * if it's currently loaded in memoru, or %NULL otherwise. Unref the non-NULL
+ * info with g_object_unref() when done with it.
*
- * Returns: (nullable) (transfer full):
* Since: 2.26
**/
CamelMessageInfo *
@@ -1443,8 +1448,14 @@ gather_changed_uids (gpointer key,
/**
* camel_folder_summary_get_changed:
+ * @summary: a #CamelFolderSummary
+ *
+ * Returns an array of changed UID-s. A UID is considered changed
+ * when its corresponding CamelMesageInfo is 'dirty' or when it has
+ * set the #CAMEL_MESSAGE_FOLDER_FLAGGED flag.
*
- * Returns: (element-type utf8) (transfer full):
+ * Returns: (element-type utf8) (transfer full): a #GPtrArray with changed UID-s.
+ * Free it with camel_folder_summary_free_array() when no longer needed.
*
* Since: 2.24
**/
@@ -1452,7 +1463,11 @@ GPtrArray *
camel_folder_summary_get_changed (CamelFolderSummary *summary)
{
GPtrArray *res;
- GHashTable *hash = g_hash_table_new_full (g_direct_hash, g_direct_equal, (GDestroyNotify)
camel_pstring_free, NULL);
+ GHashTable *hash;
+
+ g_return_val_if_fail (CAMEL_IS_FOLDER_SUMMARY (summary), NULL);
+
+ hash = g_hash_table_new_full (g_direct_hash, g_direct_equal, (GDestroyNotify) camel_pstring_free,
NULL);
camel_folder_summary_lock (summary);
@@ -1729,6 +1744,13 @@ camel_folder_summary_prepare_fetch_all (CamelFolderSummary *summary,
/**
* camel_folder_summary_load:
+ * @summary: a #CamelFolderSummary
+ * @error: return location for a #GError, or %NULL
+ *
+ * Loads the summary from the disk. It also saves any pending
+ * changes first.
+ *
+ * Returns: whether succeeded
*
* Since: 3.24
**/
@@ -2029,6 +2051,14 @@ save_message_infos_to_db (CamelFolderSummary *summary,
/**
* camel_folder_summary_save:
+ * @summary: a #CamelFolderSummary
+ * @error: return location for a #GError, or %NULL
+ *
+ * Saves the content of the @summary to disk. It does nothing,
+ * when the summary is not changed or when it doesn't support
+ * permanent save.
+ *
+ * Returns: whether succeeded
*
* Since: 3.24
**/
@@ -2125,6 +2155,13 @@ camel_folder_summary_save (CamelFolderSummary *summary,
/**
* camel_folder_summary_header_save:
+ * @summary: a #CamelFolderSummary
+ * @error: return location for a #GError, or %NULL
+ *
+ * Saves summary header information into the disk. The function does
+ * nothing, if the summary doesn't support save to disk.
+ *
+ * Returns: whether succeeded
*
* Since: 3.24
**/
@@ -2175,6 +2212,15 @@ camel_folder_summary_header_save (CamelFolderSummary *summary,
/**
* camel_folder_summary_header_load:
+ * @summary: a #CamelFolderSummary
+ * @store: a #CamelStore
+ * @folder_name: a folder name corresponding to @summary
+ * @error: return location for a #GError, or %NULL
+ *
+ * Loads a summary header for the @summary, which corresponds to @folder_name
+ * provided by @store.
+ *
+ * Returns: whether succeeded
*
* Since: 3.24
**/
@@ -2496,8 +2542,11 @@ camel_folder_summary_touch (CamelFolderSummary *summary)
/**
* camel_folder_summary_clear:
* @summary: a #CamelFolderSummary object
+ * @error: return location for a #GError, or %NULL
*
* Empty the summary contents.
+ *
+ * Returns: whether succeeded
**/
gboolean
camel_folder_summary_clear (CamelFolderSummary *summary,
diff --git a/src/camel/camel-folder-thread.c b/src/camel/camel-folder-thread.c
index 1d6c53d..e0b97cd 100644
--- a/src/camel/camel-folder-thread.c
+++ b/src/camel/camel-folder-thread.c
@@ -650,9 +650,9 @@ thread_summary (CamelFolderThread *thread,
/**
* camel_folder_thread_messages_new: (skip)
- * @folder:
- * @uids: (element-type utf8): The subset of uid's to thread. If NULL. then thread all
- * uid's in @folder.
+ * @folder: a #CamelFolder
+ * @uids: (element-type utf8): The subset of uid's to thread. If %NULL, then thread
+ * all UID-s in the @folder
* @thread_subject: thread based on subject also
*
* Thread a (subset) of the messages in a folder. And sort the result
@@ -741,7 +741,10 @@ add_present_rec (CamelFolderThread *thread,
/**
* camel_folder_thread_messages_apply:
- * @uids:(element-type utf8) (transfer none):
+ * @thread: a #CamelFolderThread
+ * @uids: (element-type utf8) (transfer none): a #GPtrArray array of UID-s
+ *
+ * Adds new @uids into the threaded tree.
**/
void
camel_folder_thread_messages_apply (CamelFolderThread *thread,
@@ -783,7 +786,7 @@ camel_folder_thread_messages_ref (CamelFolderThread *thread)
/**
* camel_folder_thread_messages_unref:
- * @thread:
+ * @thread: a #CamelFolderThread
*
* Free all memory associated with the thread descriptor @thread.
**/
diff --git a/src/camel/camel-folder.c b/src/camel/camel-folder.c
index 2d04065..7e68e70 100644
--- a/src/camel/camel-folder.c
+++ b/src/camel/camel-folder.c
@@ -1338,9 +1338,11 @@ G_DEFINE_QUARK (camel-folder-error-quark, camel_folder_error)
/**
* camel_folder_set_lock_async:
* @folder: a #CamelFolder
- * @skip_folder_lock:
+ * @skip_folder_lock: a value to set
*
- * FIXME Document me!
+ * Sets whether folder locking (camel_folder_lock() and camel_folder_unlock())
+ * should be used. When set to %FALSE, the two functions do nothing and simply
+ * return.
*
* Since: 2.30
**/
@@ -1355,6 +1357,13 @@ camel_folder_set_lock_async (CamelFolder *folder,
/**
* camel_folder_get_filename:
+ * @folder: a #CamelFolder
+ * @uid: a message UID
+ * @error: return location for a #GError, or %NULL
+ *
+ * Returns: (transfer full): a file name corresponding to a message
+ * with UID @uid. Free the returned string with g_free(), when
+ * no longer needed.
*
* Since: 2.26
**/
@@ -2060,6 +2069,7 @@ camel_folder_free_uids (CamelFolder *folder,
* camel_folder_get_uncached_uids:
* @folder: a #CamelFolder
* @uids: (element-type utf8): the array of uids to filter down to uncached ones.
+ * @error: return location for a #GError, or %NULL
*
* Returns the known-uncached uids from a list of uids. It may return uids
* which are locally cached but should never filter out a uid which is not
diff --git a/src/camel/camel-folder.h b/src/camel/camel-folder.h
index 0255382..1246281 100644
--- a/src/camel/camel-folder.h
+++ b/src/camel/camel-folder.h
@@ -72,6 +72,14 @@ typedef struct _CamelFolderPrivate CamelFolderPrivate;
/**
* CamelFolderError:
+ * @CAMEL_FOLDER_ERROR_INVALID: a generic error about invalid operation with the folder
+ * @CAMEL_FOLDER_ERROR_INVALID_STATE: the folder is in an invalid state
+ * @CAMEL_FOLDER_ERROR_NON_EMPTY: the folder is not empty
+ * @CAMEL_FOLDER_ERROR_NON_UID: requested UID is not a UID
+ * @CAMEL_FOLDER_ERROR_INSUFFICIENT_PERMISSION: insufficient permissions for the requested operation
+ * @CAMEL_FOLDER_ERROR_INVALID_PATH: the folder path is invalid
+ * @CAMEL_FOLDER_ERROR_INVALID_UID: requested UID is invalid/cannot be found
+ * @CAMEL_FOLDER_ERROR_SUMMARY_INVALID: the folder's summary is invalid/broken
*
* Since: 2.32
**/
diff --git a/src/camel/camel-gpg-context.c b/src/camel/camel-gpg-context.c
index 0b71aaa..f600f6c 100644
--- a/src/camel/camel-gpg-context.c
+++ b/src/camel/camel-gpg-context.c
@@ -2679,7 +2679,7 @@ camel_gpg_context_get_always_trust (CamelGpgContext *context)
/**
* camel_gpg_context_set_always_trust:
* @context: gpg context
- * @always_trust always truct flag
+ * @always_trust: always trust flag
*
* Sets the @always_trust flag on the gpg context which is used for
* encryption.
diff --git a/src/camel/camel-html-parser.c b/src/camel/camel-html-parser.c
index 1e5d30d..901b879 100644
--- a/src/camel/camel-html-parser.c
+++ b/src/camel/camel-html-parser.c
@@ -147,12 +147,18 @@ const gchar *camel_html_parser_attr (CamelHTMLParser *hp, const gchar *name)
/**
* camel_html_parser_attr_list:
- * @values: (element-type utf8) (inout):
+ * @hp: a #CamelHTMLParser
+ * @values: (nullable) (element-type utf8) (inout): an output #GPtrArray with values, or %NULL
*
- * Returns: (element-type utf8) (transfer none):
+ * Provides parsed array of values and attributes. Both arrays are
+ * owned by the @hp.
+ *
+ * Returns: (element-type utf8) (transfer none): a #GPtrArray of parsed attributes
*
**/
-const GPtrArray *camel_html_parser_attr_list (CamelHTMLParser *hp, const GPtrArray **values)
+const GPtrArray *
+camel_html_parser_attr_list (CamelHTMLParser *hp,
+ const GPtrArray **values)
{
if (values)
*values = hp->priv->values;
diff --git a/src/camel/camel-index.c b/src/camel/camel-index.c
index 8af9415..c95964e 100644
--- a/src/camel/camel-index.c
+++ b/src/camel/camel-index.c
@@ -204,8 +204,11 @@ camel_index_has_name (CamelIndex *idx,
/**
* camel_index_add_name:
* @index: a #CamelIndex
+ * @name: a name to add
*
- * Returns: (transfer none) (nullable):
+ * Returns: (transfer none) (nullable): a #CamelIndexName with
+ * added given @name, or %NULL, when the @name could not be
+ * added.
**/
CamelIndexName *
camel_index_add_name (CamelIndex *index,
@@ -246,8 +249,10 @@ camel_index_write_name (CamelIndex *idx,
/**
* camel_index_find_name:
* @index: a #CamelIndex
+ * @name: a name to find
*
- * Returns: (transfer none) (nullable):
+ * Returns: (transfer none) (nullable): a #CamelIndexCursor with
+ * the given @name, or %NULL< when not found.
**/
CamelIndexCursor *
camel_index_find_name (CamelIndex *index,
@@ -266,26 +271,35 @@ camel_index_find_name (CamelIndex *index,
return NULL;
}
+/**
+ * camel_index_delete_name:
+ * @index: a #CamelIndex
+ * @name: a name to delete
+ *
+ * Deletes the given @name from @index.
+ **/
void
-camel_index_delete_name (CamelIndex *idx,
+camel_index_delete_name (CamelIndex *index,
const gchar *name)
{
CamelIndexClass *class;
- g_return_if_fail (CAMEL_IS_INDEX (idx));
+ g_return_if_fail (CAMEL_IS_INDEX (index));
- class = CAMEL_INDEX_GET_CLASS (idx);
+ class = CAMEL_INDEX_GET_CLASS (index);
g_return_if_fail (class->delete_name != NULL);
- if ((idx->state & CAMEL_INDEX_DELETED) == 0)
- class->delete_name (idx, name);
+ if ((index->state & CAMEL_INDEX_DELETED) == 0)
+ class->delete_name (index, name);
}
/**
* camel_index_find:
* @index: a #CamelIndex
+ * @word: a word to find
*
- * Returns: (transfer none) (nullable):
+ * Returns: (transfer none) (nullable): a #CamelIndexCursor object with
+ * the given @word, or %NULL, when not found
**/
CamelIndexCursor *
camel_index_find (CamelIndex *index,
@@ -318,7 +332,8 @@ camel_index_find (CamelIndex *index,
* camel_index_words:
* @index: a #CamelIndex
*
- * Returns: (transfer none) (nullable):
+ * Returns: (transfer none) (nullable): a #CamelIndexCursor containing
+ * all words of the @index, or %NULL, when there are none
**/
CamelIndexCursor *
camel_index_words (CamelIndex *index)
diff --git a/src/camel/camel-lock.c b/src/camel/camel-lock.c
index 6bbda77..9132b65 100644
--- a/src/camel/camel-lock.c
+++ b/src/camel/camel-lock.c
@@ -62,12 +62,15 @@
/**
* camel_lock_dot:
- * @path:
+ * @path: a path to lock
* @error: return location for a #GError, or %NULL
*
* Create an exclusive lock using .lock semantics.
* All locks are equivalent to write locks (exclusive).
*
+ * The function does nothing and returns success (zero),
+ * when dot locking had not been compiled.
+ *
* Returns: -1 on error, sets @ex appropriately.
**/
gint
@@ -158,9 +161,11 @@ camel_lock_dot (const gchar *path,
/**
* camel_unlock_dot:
- * @path:
+ * @path: a path to unlock
*
* Attempt to unlock a .lock lock.
+ *
+ * The function does nothing, when dot locking had not been compiled.
**/
void
camel_unlock_dot (const gchar *path)
@@ -179,8 +184,8 @@ camel_unlock_dot (const gchar *path)
/**
* camel_lock_fcntl:
- * @fd:
- * @type:
+ * @fd: a file descriptor
+ * @type: a #CamelLockType
* @error: return location for a #GError, or %NULL
*
* Create a lock using fcntl(2).
@@ -188,6 +193,9 @@ camel_unlock_dot (const gchar *path)
* @type is CAMEL_LOCK_WRITE or CAMEL_LOCK_READ,
* to create exclusive or shared read locks
*
+ * The function does nothing and returns success (zero),
+ * when fcntl locking had not been compiled.
+ *
* Returns: -1 on error.
**/
gint
@@ -227,9 +235,11 @@ camel_lock_fcntl (gint fd,
/**
* camel_unlock_fcntl:
- * @fd:
+ * @fd: a file descriptor
*
* Unlock an fcntl lock.
+ *
+ * The function does nothing, when fcntl locking had not been compiled.
**/
void
camel_unlock_fcntl (gint fd)
@@ -247,8 +257,8 @@ camel_unlock_fcntl (gint fd)
/**
* camel_lock_flock:
- * @fd:
- * @type:
+ * @fd: a file descriptor
+ * @type: a #CamelLockType
* @error: return location for a #GError, or %NULL
*
* Create a lock using flock(2).
@@ -256,6 +266,9 @@ camel_unlock_fcntl (gint fd)
* @type is CAMEL_LOCK_WRITE or CAMEL_LOCK_READ,
* to create exclusive or shared read locks
*
+ * The function does nothing and returns success (zero),
+ * when flock locking had not been compiled.
+ *
* Returns: -1 on error.
**/
gint
@@ -287,9 +300,11 @@ camel_lock_flock (gint fd,
/**
* camel_unlock_flock:
- * @fd:
+ * @fd: a file descriptor
*
* Unlock an flock lock.
+ *
+ * The function does nothing, when flock locking had not been compiled.
**/
void
camel_unlock_flock (gint fd)
diff --git a/src/camel/camel-mempool.c b/src/camel/camel-mempool.c
index 2c9bc2b..e1b3403 100644
--- a/src/camel/camel-mempool.c
+++ b/src/camel/camel-mempool.c
@@ -60,7 +60,7 @@ struct _CamelMemPool {
* However, each allocation cannot be freed individually, only all
* or nothing.
*
- * Returns:
+ * Returns: (transfer full): a newly allocated #CamelMemPool
*
* Since: 2.32
**/
@@ -96,7 +96,7 @@ camel_mempool_new (gint blocksize,
/**
* camel_mempool_alloc: (skip)
* @pool: a #CamelMemPool
- * @size:
+ * @size: requested size to allocate
*
* Allocate a new data block in the mempool. Size will
* be rounded up to the mempool's alignment restrictions
diff --git a/src/camel/camel-message-info.c b/src/camel/camel-message-info.c
index d192327..03b4768 100644
--- a/src/camel/camel-message-info.c
+++ b/src/camel/camel-message-info.c
@@ -1291,7 +1291,7 @@ camel_message_info_get_folder_flagged (const CamelMessageInfo *mi)
/**
* camel_message_info_set_folder_flagged:
* @mi: a #CamelMessageInfo
- * folder_flagged: a value to set to
+ * @folder_flagged: a value to set to
*
* Changes the folder-flagged flag to the @folder_flagged value. See
* camel_message_info_get_folder_flagged() for more information about
@@ -1880,6 +1880,7 @@ camel_message_info_get_user_tag (const CamelMessageInfo *mi,
/**
* camel_message_info_dup_user_tag:
* @mi: a #CamelMessageInfo
+ * @name: user tag name
*
* Returns: (transfer full) (nullable): Value of the user tag as newly allocated
* string, or %NULL when it is not set. Free it with g_free() when no longer needed.
diff --git a/src/camel/camel-mime-filter.c b/src/camel/camel-mime-filter.c
index 0141c9e..1ea7770 100644
--- a/src/camel/camel-mime-filter.c
+++ b/src/camel/camel-mime-filter.c
@@ -296,7 +296,7 @@ camel_mime_filter_reset (CamelMimeFilter *filter)
/**
* camel_mime_filter_backup:
* @filter: a #CamelMimeFilter object
- * @data (array length=length): data buffer to backup
+ * @data: (array length=length): data buffer to backup
* @length: length of @data
*
* Saves @data to be used as prespace input data to the next call to
diff --git a/src/camel/camel-mime-message.c b/src/camel/camel-mime-message.c
index 195b1f2..4bcd5e8 100644
--- a/src/camel/camel-mime-message.c
+++ b/src/camel/camel-mime-message.c
@@ -1437,8 +1437,8 @@ cmm_dump_rec (CamelMimeMessage *msg,
/**
* camel_mime_message_dump:
- * @message:
- * @body:
+ * @message: a #CamelMimeMessage
+ * @body: whether to dump also message body
*
* Dump information about the mime message to stdout.
*
diff --git a/src/camel/camel-mime-part-utils.c b/src/camel/camel-mime-part-utils.c
index 77ab61b..acc9926 100644
--- a/src/camel/camel-mime-part-utils.c
+++ b/src/camel/camel-mime-part-utils.c
@@ -81,11 +81,19 @@ simple_data_wrapper_construct_from_parser (CamelDataWrapper *dw,
/**
* camel_mime_part_construct_content_from_parser:
+ * @mime_part: a #CamelMimePart
+ * @mp: a #CamelMimeParser
+ * @cancellable: optional #GCancellable object, or %NULL
+ * @error: return location for a #GError, or %NULL
+ *
+ * Constructs the contnet of @mime_part from the given mime parser.
+ *
+ * Returns: whether succeeded
*
* Since: 2.24
**/
gboolean
-camel_mime_part_construct_content_from_parser (CamelMimePart *dw,
+camel_mime_part_construct_content_from_parser (CamelMimePart *mime_part,
CamelMimeParser *mp,
GCancellable *cancellable,
GError **error)
@@ -95,7 +103,7 @@ camel_mime_part_construct_content_from_parser (CamelMimePart *dw,
gchar *encoding;
gboolean success = TRUE;
- g_return_val_if_fail (CAMEL_IS_MIME_PART (dw), FALSE);
+ g_return_val_if_fail (CAMEL_IS_MIME_PART (mime_part), FALSE);
ct = camel_mime_parser_content_type (mp);
@@ -140,9 +148,8 @@ camel_mime_part_construct_content_from_parser (CamelMimePart *dw,
if (encoding)
camel_data_wrapper_set_encoding (content, camel_transfer_encoding_from_string
(encoding));
- /* would you believe you have to set this BEFORE you set the content object??? oh my god
!!!! */
- camel_data_wrapper_set_mime_type_field (content, camel_mime_part_get_content_type (dw));
- camel_medium_set_content ((CamelMedium *) dw, content);
+ camel_data_wrapper_set_mime_type_field (content, camel_mime_part_get_content_type
(mime_part));
+ camel_medium_set_content (CAMEL_MEDIUM (mime_part), content);
g_object_unref (content);
}
diff --git a/src/camel/camel-mime-utils.c b/src/camel/camel-mime-utils.c
index c49d9a1..641d8ab 100644
--- a/src/camel/camel-mime-utils.c
+++ b/src/camel/camel-mime-utils.c
@@ -3102,11 +3102,11 @@ header_references_decode_single (const gchar **in, GSList **list)
/**
* camel_header_references_decode:
- * @in:
+ * @in: References header value
*
* Generate a list of references, from most recent up.
*
- * Returns: (element-type utf8) (transfer full):
+ * Returns: (element-type utf8) (transfer full): a list of references decoedd from @in
**/
GSList *
camel_header_references_decode (const gchar *in)
@@ -3424,8 +3424,10 @@ header_decode_param_list (const gchar **in)
/**
* camel_header_param_list_decode:
+ * @in: (nullable): a header param value to decode
*
- * Returns: (transfer full):
+ * Returns: (nullable) (transfer full): Decode list of parameters.
+ * Free with camel_header_param_list_free() when done with it.
**/
struct _camel_header_param *
camel_header_param_list_decode (const gchar *in)
diff --git a/src/camel/camel-msgport.c b/src/camel/camel-msgport.c
index 75ee41f..b4d8112 100644
--- a/src/camel/camel-msgport.c
+++ b/src/camel/camel-msgport.c
@@ -240,6 +240,8 @@ msgport_sync_with_prpipe (PRFileDesc *prfd)
/**
* camel_msgport_new: (skip)
*
+ * Returns: (transfer full): a new #CamelMsgPort
+ *
* Since: 2.24
**/
CamelMsgPort *
@@ -259,6 +261,7 @@ camel_msgport_new (void)
/**
* camel_msgport_destroy: (skip)
+ * @msgport: a #CamelMsgPort
*
* Since: 2.24
**/
@@ -282,6 +285,7 @@ camel_msgport_destroy (CamelMsgPort *msgport)
/**
* camel_msgport_fd: (skip)
+ * @msgport: a #CamelMsgPort
*
* Since: 2.24
**/
@@ -303,6 +307,7 @@ camel_msgport_fd (CamelMsgPort *msgport)
/**
* camel_msgport_prfd: (skip)
+ * @msgport: a #CamelMsgPort
*
* Returns: (transfer none):
*
@@ -326,6 +331,8 @@ camel_msgport_prfd (CamelMsgPort *msgport)
/**
* camel_msgport_push: (skip)
+ * @msgport: a #CamelMsgPort
+ * @msg: a #CamelMsg
*
* Since: 2.24
**/
@@ -377,6 +384,7 @@ camel_msgport_push (CamelMsgPort *msgport,
/**
* camel_msgport_pop: (skip)
+ * @msgport: a #CamelMsgPort
*
* Since: 2.24
**/
@@ -405,6 +413,7 @@ camel_msgport_pop (CamelMsgPort *msgport)
/**
* camel_msgport_try_pop: (skip)
+ * @msgport: a #CamelMsgPort
*
* Since: 2.24
**/
@@ -460,6 +469,7 @@ camel_msgport_timeout_pop (CamelMsgPort *msgport,
/**
* camel_msgport_reply: (skip)
+ * @msg: a #CamelMsg
*
* Since: 2.24
**/
diff --git a/src/camel/camel-net-utils.c b/src/camel/camel-net-utils.c
index a805348..93e1409 100644
--- a/src/camel/camel-net-utils.c
+++ b/src/camel/camel-net-utils.c
@@ -678,8 +678,16 @@ cs_getaddrinfo (gpointer data)
/**
* camel_getaddrinfo:
+ * @name: an address name to resolve
+ * @service: a service name to use
+ * @hints: (nullable): an #addrinfo hints, or %NULL
+ * @cancellable: optional #GCancellable object, or %NULL
+ * @error: return location for a #GError, or %NULL
*
- * Returns: (transfer none):
+ * Resolves a host @name and returns an information about its address.
+ *
+ * Returns: (transfer full) (nullable): a newly allocated #addrinfo. Free it
+ * with camel_freeaddrinfo() when done with it.
*
* Since: 2.22
**/
@@ -754,12 +762,19 @@ camel_getaddrinfo (const gchar *name,
/**
* camel_freeaddrinfo:
+ * @host: (nullable): a host address information structure to free, or %NULL
+ *
+ * Frees a structure returned with camel_getaddrinfo(). It does
+ * nothing when the @host is %NULL.
*
* Since: 2.22
**/
void
camel_freeaddrinfo (struct addrinfo *host)
{
+ if (!host)
+ return;
+
#ifdef NEED_ADDRINFO
while (host) {
struct addrinfo *next = host->ai_next;
diff --git a/src/camel/camel-nntp-address.c b/src/camel/camel-nntp-address.c
index 60729dc..a67ccf6 100644
--- a/src/camel/camel-nntp-address.c
+++ b/src/camel/camel-nntp-address.c
@@ -176,7 +176,7 @@ camel_nntp_address_new (void)
/**
* camel_nntp_address_add:
* @addr: nntp address object
- * @name:
+ * @name: a new NNTP address to add
*
* Add a new nntp address to the address object. Duplicates are not added twice.
*
diff --git a/src/camel/camel-object.h b/src/camel/camel-object.h
index 5e76c01..6ba5756 100644
--- a/src/camel/camel-object.h
+++ b/src/camel/camel-object.h
@@ -82,6 +82,7 @@ typedef enum {
/**
* CamelError:
+ * @CAMEL_ERROR_GENERIC: a generic (fallback) error code
*
* Since: 2.32
**/
diff --git a/src/camel/camel-offline-store.c b/src/camel/camel-offline-store.c
index 3ca0db6..b04d026 100644
--- a/src/camel/camel-offline-store.c
+++ b/src/camel/camel-offline-store.c
@@ -259,6 +259,14 @@ camel_offline_store_set_online_sync (CamelOfflineStore *store,
/**
* camel_offline_store_prepare_for_offline_sync:
+ * @store: a #CamelOfflineStore
+ * @cancellable: optional #GCancellable object, or %NULL
+ * @error: return location for a #GError, or %NULL
+ *
+ * Downloads messages for offline, when setup to do so and when
+ * the host is reachable.
+ *
+ * Returns: whether succeeded
*
* Since: 2.22
**/
diff --git a/src/camel/camel-sasl-gssapi.c b/src/camel/camel-sasl-gssapi.c
index 536fea9..ec370df 100644
--- a/src/camel/camel-sasl-gssapi.c
+++ b/src/camel/camel-sasl-gssapi.c
@@ -578,6 +578,7 @@ camel_sasl_gssapi_is_available (void)
/**
* camel_sasl_gssapi_override_host_and_user:
+ * @sasl: a #CamelSaslGssapi
* @override_host: (nullable): Host name to use during challenge processing; can be %NULL
* @override_user: (nullable): User name to use during challenge processing; can be %NULL
*
diff --git a/src/camel/camel-search-sql-sexp.c b/src/camel/camel-search-sql-sexp.c
index 2ecbf21..c317651 100644
--- a/src/camel/camel-search-sql-sexp.c
+++ b/src/camel/camel-search-sql-sexp.c
@@ -741,39 +741,48 @@ static struct {
/**
* camel_sexp_to_sql_sexp:
+ * @sexp: a search expression to convert
+ *
+ * Converts a search expression to an SQL 'WHERE' part statement,
+ * without the 'WHERE' keyword.
+ *
+ * Returns: (transfer full): a newly allocated string, an SQL 'WHERE' part statement,
+ * or %NULL, when could not convert it. Free it with g_free(), when done with it.
*
* Since: 2.26
**/
gchar *
-camel_sexp_to_sql_sexp (const gchar *sql)
+camel_sexp_to_sql_sexp (const gchar *sexp)
{
- CamelSExp *sexp;
+ CamelSExp *sexpobj;
CamelSExpResult *r;
gint i;
gchar *res = NULL;
gboolean contains_unknown_column = FALSE;
- sexp = camel_sexp_new ();
+ g_return_val_if_fail (sexp != NULL, NULL);
+
+ sexpobj = camel_sexp_new ();
for (i = 0; i < G_N_ELEMENTS (symbols); i++) {
if (symbols[i].immediate)
- camel_sexp_add_ifunction (sexp, 0, symbols[i].name,
+ camel_sexp_add_ifunction (sexpobj, 0, symbols[i].name,
(CamelSExpIFunc) symbols[i].func, &contains_unknown_column);
else
camel_sexp_add_function (
- sexp, 0, symbols[i].name,
+ sexpobj, 0, symbols[i].name,
symbols[i].func, &contains_unknown_column);
}
- camel_sexp_input_text (sexp, sql, strlen (sql));
- if (camel_sexp_parse (sexp)) {
- g_object_unref (sexp);
+ camel_sexp_input_text (sexpobj, sexp, strlen (sexp));
+ if (camel_sexp_parse (sexpobj)) {
+ g_object_unref (sexpobj);
return NULL;
}
- r = camel_sexp_eval (sexp);
+ r = camel_sexp_eval (sexpobj);
if (!r) {
- g_object_unref (sexp);
+ g_object_unref (sexpobj);
return NULL;
}
@@ -781,8 +790,8 @@ camel_sexp_to_sql_sexp (const gchar *sql)
res = g_strdup (r->value.string);
}
- camel_sexp_result_free (sexp, r);
- g_object_unref (sexp);
+ camel_sexp_result_free (sexpobj, r);
+ g_object_unref (sexpobj);
return res;
}
diff --git a/src/camel/camel-service.h b/src/camel/camel-service.h
index fe04223..7d92bd5 100644
--- a/src/camel/camel-service.h
+++ b/src/camel/camel-service.h
@@ -72,6 +72,11 @@ typedef struct _CamelServicePrivate CamelServicePrivate;
/**
* CamelServiceError:
+ * @CAMEL_SERVICE_ERROR_INVALID: a generic service error code
+ * @CAMEL_SERVICE_ERROR_URL_INVALID: the URL for the service is invalid
+ * @CAMEL_SERVICE_ERROR_UNAVAILABLE: the service is unavailable
+ * @CAMEL_SERVICE_ERROR_CANT_AUTHENTICATE: failed to authenitcate
+ * @CAMEL_SERVICE_ERROR_NOT_CONNECTED: the service is not connected
*
* Since: 2.32
**/
diff --git a/src/camel/camel-session.c b/src/camel/camel-session.c
index 5b6e0a6..a5868ab 100644
--- a/src/camel/camel-session.c
+++ b/src/camel/camel-session.c
@@ -1304,6 +1304,12 @@ camel_session_user_alert (CamelSession *session,
/**
* camel_session_lookup_addressbook:
+ * @session: a #CamelSession
+ * @name: a name/address to lookup for
+ *
+ * Looks up for the @name in address books.
+ *
+ * Returns: whether found the @name in any address book.
*
* Since: 2.22
**/
@@ -1592,9 +1598,12 @@ camel_session_set_junk_headers (CamelSession *session,
/**
* camel_session_get_junk_headers:
+ * @session: a #CamelSession
+ *
+ * Returns: (element-type utf8 utf8) (transfer none): Currently used junk
+ * headers as a hash table, previously set by camel_session_set_junk_headers().
*
* Since: 2.22
- * Returns: (element-type utf8 utf8) (transfer none):
**/
const GHashTable *
camel_session_get_junk_headers (CamelSession *session)
diff --git a/src/camel/camel-sexp.c b/src/camel/camel-sexp.c
index 5487d79..83658f8 100644
--- a/src/camel/camel-sexp.c
+++ b/src/camel/camel-sexp.c
@@ -164,6 +164,12 @@ static const GScannerConfig scanner_config =
/**
* camel_sexp_fatal_error:
+ * @sexp: a #CamelSExp
+ * @why: a string format to use
+ * @...: parameters for the format
+ *
+ * Sets an error from the given format and stops execution.
+ * Int replaces previously set error, if any.
*
* Since: 3.4
**/
@@ -189,6 +195,9 @@ camel_sexp_fatal_error (CamelSExp *sexp,
/**
* camel_sexp_error:
+ * @sexp: a #CamelSExp
+ *
+ * Returns: (nullable): Set error string on the @sexp, or %NULL, when none is set
*
* Since: 3.4
**/
@@ -200,6 +209,11 @@ camel_sexp_error (CamelSExp *sexp)
/**
* camel_sexp_result_new: (skip)
+ * @sexp: a #CamelSExp
+ * @type: type of the result, one of #CamelSExpResultType
+ *
+ * Returns: (transfer full): A new #CamelSExpResult result structure, associated with @sexp.
+ * Free with camel_sexp_result_free(), when no longer needed.
*
* Since: 3.4
**/
@@ -220,37 +234,47 @@ camel_sexp_result_new (CamelSExp *sexp,
/**
* camel_sexp_result_free:
+ * @sexp: a #CamelSExp
+ * @result: (nullable): a #CamelSExpResult to free
+ *
+ * Frees the @result and its internal data. Does nothing,
+ * when the @result is %NULL.
*
* Since: 3.4
**/
void
camel_sexp_result_free (CamelSExp *sexp,
- CamelSExpResult *term)
+ CamelSExpResult *result)
{
- if (term == NULL)
+ if (result == NULL)
return;
- switch (term->type) {
+ switch (result->type) {
case CAMEL_SEXP_RES_ARRAY_PTR:
- g_ptr_array_free (term->value.ptrarray, TRUE);
+ g_ptr_array_free (result->value.ptrarray, TRUE);
break;
case CAMEL_SEXP_RES_BOOL:
case CAMEL_SEXP_RES_INT:
case CAMEL_SEXP_RES_TIME:
break;
case CAMEL_SEXP_RES_STRING:
- g_free (term->value.string);
+ g_free (result->value.string);
break;
case CAMEL_SEXP_RES_UNDEFINED:
break;
default:
g_return_if_reached ();
}
- camel_memchunk_free (sexp->priv->result_chunks, term);
+ camel_memchunk_free (sexp->priv->result_chunks, result);
}
/**
* camel_sexp_resultv_free:
+ * @sexp: a #CamelSExp
+ * @argc: a count of the @argv
+ * @argv: (array length=argc): an array of #CamelSExpResult to free
+ *
+ * Frees an array of results.
*
* Since: 3.4
**/
@@ -769,6 +793,13 @@ term_eval_begin (CamelSExp *sexp,
/**
* camel_sexp_term_eval: (skip)
+ * @sexp: a #CamelSExp
+ * @term: a #CamelSExpTerm to evaluate
+ *
+ * Evaluates a part of the expression.
+ *
+ * Returns: (transfer full): a newly allocated result of the evaluation. Free
+ * the returned pointer with camel_sexp_result_free(), when no longer needed.
*
* Since: 3.4
**/
@@ -1289,6 +1320,9 @@ parse_values (CamelSExp *sexp,
/**
* camel_sexp_parse_value: (skip)
+ * @sexp: a #CamelSExp
+ *
+ * Returns: (nullable) (transfer none): a #CamelSExpTerm of the next token, or %NULL when there is none.
*
* Since: 3.4
**/
@@ -1545,6 +1579,8 @@ camel_sexp_init (CamelSExp *sexp)
/**
* camel_sexp_new:
*
+ * Returns: (transfer full): a new #CamelSExp
+ *
* Since: 3.4
**/
CamelSExp *
@@ -1555,7 +1591,14 @@ camel_sexp_new (void)
/**
* camel_sexp_add_function:
- * @func: (scope call):
+ * @sexp: a #CamelSExp
+ * @scope: a scope
+ * @name: a function name
+ * @func: (scope call) (closure user_data): a function callback
+ * @user_data: user data for @func
+ *
+ * Adds a function symbol which can not perform short evaluation.
+ * Use camel_sexp_add_ifunction() for functions which can.
*
* Since: 3.4
**/
@@ -1584,7 +1627,15 @@ camel_sexp_add_function (CamelSExp *sexp,
/**
* camel_sexp_add_ifunction:
- * @func: (scope call):
+ * @sexp: a #CamelSExp
+ * @scope: a scope
+ * @name: a function name
+ * @ifunc: (scope call) (closure user_data): a function callback
+ * @user_data: user data for @ifunc
+ *
+ * Adds a function symbol which can perform short evaluation,
+ * or doesn't execute everything. Use camel_sexp_add_function()
+ * for any other types of the function symbols.
*
* Since: 3.4
**/
@@ -1613,13 +1664,19 @@ camel_sexp_add_ifunction (CamelSExp *sexp,
/**
* camel_sexp_add_variable:
+ * @sexp: a #CamelSExp
+ * @scope: a scope
+ * @name: a variable name
+ * @value: a variable value, as a #CamelSExpTerm
+ *
+ * Adds a variable named @name to the given @scope, set to the given @value.
*
* Since: 3.4
**/
void
camel_sexp_add_variable (CamelSExp *sexp,
guint scope,
- gchar *name,
+ const gchar *name,
CamelSExpTerm *value)
{
CamelSExpSymbol *sym;
@@ -1637,6 +1694,11 @@ camel_sexp_add_variable (CamelSExp *sexp,
/**
* camel_sexp_remove_symbol:
+ * @sexp: a #CamelSExp
+ * @scope: a scope
+ * @name: a symbol name
+ *
+ * Revoes a symbol from a scope.
*
* Since: 3.4
**/
@@ -1663,6 +1725,12 @@ camel_sexp_remove_symbol (CamelSExp *sexp,
/**
* camel_sexp_set_scope:
+ * @sexp: a #CamelSExp
+ * @scope: a scope to set
+ *
+ * sets the current scope for the scanner.
+ *
+ * Returns: the previous scope id
*
* Since: 3.4
**/
@@ -1677,6 +1745,11 @@ camel_sexp_set_scope (CamelSExp *sexp,
/**
* camel_sexp_input_text:
+ * @sexp: a #CamelSExp
+ * @text: a text buffer to scan
+ * @len: the length of the text buffer
+ *
+ * Prepares to scan a text buffer.
*
* Since: 3.4
**/
@@ -1693,6 +1766,10 @@ camel_sexp_input_text (CamelSExp *sexp,
/**
* camel_sexp_input_file:
+ * @sexp: a #CamelSExp
+ * @fd: a file descriptor
+ *
+ * Prepares to scan a file.
*
* Since: 3.4
**/
@@ -1707,6 +1784,7 @@ camel_sexp_input_file (CamelSExp *sexp,
/**
* camel_sexp_parse:
+ * @sexp: a #CamelSExp
*
* Since: 3.4
**/
@@ -1730,6 +1808,7 @@ camel_sexp_parse (CamelSExp *sexp)
/**
* camel_sexp_eval: (skip)
+ * @sexp: a #CamelSExp
*
* Since: 3.4
**/
@@ -1749,7 +1828,7 @@ camel_sexp_eval (CamelSExp *sexp)
/**
* e_cal_backend_sexp_evaluate_occur_times:
- * @f: An #CamelSExp object.
+ * @sexp: a #CamelSExp
* @start: Start of the time window will be stored here.
* @end: End of the time window will be stored here.
*
@@ -1792,8 +1871,8 @@ camel_sexp_evaluate_occur_times (CamelSExp *sexp,
/**
* camel_sexp_encode_bool:
- * @string:
- * @v_bool:
+ * @string: Destination #GString
+ * @v_bool: the value
*
* Encode a bool into an s-expression @string. Bools are
* encoded using #t #f syntax.
@@ -1812,7 +1891,7 @@ camel_sexp_encode_bool (GString *string,
/**
* camel_sexp_encode_string:
- * @string: Destination string.
+ * @string: Destination #Gstring
* @v_string: String expression.
*
* Add a c string @v_string to the s-expression stored in
diff --git a/src/camel/camel-sexp.h b/src/camel/camel-sexp.h
index d825860..f400d7d 100644
--- a/src/camel/camel-sexp.h
+++ b/src/camel/camel-sexp.h
@@ -105,7 +105,14 @@ struct _CamelSExpResult {
/**
* CamelSExpFunc:
- * @argv: (inout) (array length=argc):
+ * @sexp: a #CamelSExp
+ * @argc: count of arguments
+ * @argv: (in) (array length=argc): array of values of the arguments
+ * @user_data: user data as passed to camel_sexp_add_function()
+ *
+ * Callback type for function symbols used with camel_sexp_add_function().
+ *
+ * Returns: Result of the function call, allocated by camel_sexp_result_new().
*
* Since: 3.4
**/
@@ -117,12 +124,19 @@ typedef CamelSExpResult *
/**
* CamelSExpIFunc:
- * @argv: (inout) (array length=argc):
+ * @argc: count of arguments
+ * @argv: (in) (array length=argc): array of values of the arguments
+ * @user_data: user data as passed to camel_sexp_add_ifunction()
+ *
+ * Callback type for function symbols used with camel_sexp_add_ifunction().
+ *
+ * Returns: Result of the function call, allocated by camel_sexp_result_new().
*
* Since: 3.4
**/
typedef CamelSExpResult *
- (*CamelSExpIFunc) (CamelSExp *sexp, gint argc,
+ (*CamelSExpIFunc) (CamelSExp *sexp,
+ gint argc,
CamelSExpTerm **argv,
gpointer user_data);
@@ -222,11 +236,11 @@ void camel_sexp_add_function (CamelSExp *sexp,
void camel_sexp_add_ifunction (CamelSExp *sexp,
guint scope,
const gchar *name,
- CamelSExpIFunc func,
+ CamelSExpIFunc ifunc,
gpointer user_data);
void camel_sexp_add_variable (CamelSExp *sexp,
guint scope,
- gchar *name,
+ const gchar *name,
CamelSExpTerm *value);
void camel_sexp_remove_symbol (CamelSExp *sexp,
guint scope,
@@ -248,7 +262,7 @@ CamelSExpResult *
camel_sexp_result_new (CamelSExp *sexp,
gint type);
void camel_sexp_result_free (CamelSExp *sexp,
- CamelSExpResult *term);
+ CamelSExpResult *result);
/* used in normal functions if they have to abort, to free their arguments */
void camel_sexp_resultv_free (CamelSExp *sexp,
diff --git a/src/camel/camel-utf8.c b/src/camel/camel-utf8.c
index d682b80..ce8b1d4 100644
--- a/src/camel/camel-utf8.c
+++ b/src/camel/camel-utf8.c
@@ -26,8 +26,8 @@
/**
* camel_utf8_putc:
- * @ptr:
- * @c:
+ * @ptr: (inout): pointer to write the character to
+ * @c: a Unicode character to write
*
* Output a 32 bit unicode character as utf8 octets. At most 4 octets will
* be written to @ptr. @ptr will be advanced to the next character position.
@@ -60,7 +60,7 @@ camel_utf8_putc (guchar **ptr,
/**
* camel_utf8_getc:
- * @ptr:
+ * @ptr: (inout): a pointer to read the characted from
*
* Get a Unicode character from a utf8 stream. @ptr will be advanced
* to the next character position. Invalid utf8 characters will be
diff --git a/src/camel/camel-vee-folder.c b/src/camel/camel-vee-folder.c
index e7799b8..5e6937f 100644
--- a/src/camel/camel-vee-folder.c
+++ b/src/camel/camel-vee-folder.c
@@ -1482,7 +1482,7 @@ camel_vee_folder_remove_folder (CamelVeeFolder *vfolder,
* camel_vee_folder_rebuild_folder:
* @vfolder: Virtual Folder object
* @subfolder: source CamelFolder to add to @vfolder
- * @cancellable:
+ * @cancellable: optional #GCancellable object, or %NULL
*
* Rebuild the folder @subfolder, if it should be.
**/
diff --git a/src/camel/camel-vee-store.c b/src/camel/camel-vee-store.c
index 0b5d31a..2b72e86 100644
--- a/src/camel/camel-vee-store.c
+++ b/src/camel/camel-vee-store.c
@@ -564,7 +564,7 @@ camel_vee_store_init (CamelVeeStore *vee_store)
*
* Create a new #CamelVeeStore object.
*
- * Returns: new #CamelVeeStore object
+ * Returns: (transfer full): new #CamelVeeStore object
**/
CamelVeeStore *
camel_vee_store_new (void)
@@ -574,10 +574,9 @@ camel_vee_store_new (void)
/**
* camel_vee_store_get_vee_data_cache:
+ * @vstore: a #CamelVeeStore
*
- * FIXME Document me!
- *
- * Returns: (type CamelVeeFolder) (transfer none):
+ * Returns: (type CamelVeeFolder) (transfer none): the associated #CamelVeeDataCache
*
* Since: 3.6
**/
@@ -591,10 +590,10 @@ camel_vee_store_get_vee_data_cache (CamelVeeStore *vstore)
/**
* camel_vee_store_get_unmatched_folder:
+ * @vstore: a #CamelVeeStore
*
- * FIXME Document me!
- *
- * Returns: (transfer none):
+ * Returns: (transfer none): the Unmatched folder instance, or %NULL,
+ * when it's disabled.
*
* Since: 3.6
**/
@@ -611,8 +610,9 @@ camel_vee_store_get_unmatched_folder (CamelVeeStore *vstore)
/**
* camel_vee_store_get_unmatched_enabled:
+ * @vstore: a #CamelVeeStore
*
- * FIXME Document me!
+ * Returns: whether Unmatched folder processing is enabled
*
* Since: 3.6
**/
@@ -626,8 +626,10 @@ camel_vee_store_get_unmatched_enabled (CamelVeeStore *vstore)
/**
* camel_vee_store_set_unmatched_enabled:
+ * @vstore: a #CamelVeeStore
+ * @is_enabled: value to set
*
- * FIXME Document me!
+ * Sets whether the Unmatched folder processing is enabled.
*
* Since: 3.6
**/
@@ -686,11 +688,13 @@ add_to_unmatched_folder_cb (CamelVeeMessageInfoData *mi_data,
/**
* camel_vee_store_note_subfolder_used:
- * @vstore:
- * @subfolder:
- * @used_by: (type CamelVeeFolder):
+ * @vstore: a #CamelVeeStore
+ * @subfolder: a #CamelFolder
+ * @used_by: (type CamelVeeFolder): a #CamelVeeFolder
*
- * FIXME Document me!
+ * Notes that the @subfolder is used by @used_by folder, which
+ * is used to determine what folders will be included in
+ * the Unmatched folders.
*
* Since: 3.6
**/
@@ -768,11 +772,13 @@ remove_vuid_count_record_cb (CamelVeeMessageInfoData *mi_data,
/**
* camel_vee_store_note_subfolder_unused:
- * @vstore:
- * @subfolder:
- * @unused_by: (type CamelVeeFolder):
+ * @vstore: a #CamelVeeStore
+ * @subfolder: a #CamelFolder
+ * @unused_by: (type CamelVeeFolder): a #CamelVeeFolder
*
- * FIXME Document me!
+ * This is a counter part of camel_vee_store_note_subfolder_used(). Once
+ * the @subfolder is claimed to be not used by all folders its message infos
+ * are removed from the Unmatched folder.
*
* Since: 3.6
**/
@@ -820,11 +826,12 @@ camel_vee_store_note_subfolder_unused (CamelVeeStore *vstore,
/**
* camel_vee_store_note_vuid_used:
- * @vstore:
- * @mi_data:
- * @used_by: (type CamelVeeFolder):
+ * @vstore: a #CamelVeeStore
+ * @mi_data: a #CamelVeeMessageInfoData
+ * @used_by: (type CamelVeeFolder): a #CamelVeeFolder
*
- * FIXME Document me!
+ * Notes the @mi_data is used by the @used_by virtual folder, which
+ * removes it from the Unmatched folder, if not used anywhere else.
*
* Since: 3.6
**/
@@ -880,11 +887,13 @@ camel_vee_store_note_vuid_used (CamelVeeStore *vstore,
/**
* camel_vee_store_note_vuid_unused:
- * @vstore:
- * @mi_data:
- * @unused_by: (type CamelVeeFolder):
+ * @vstore: a #CamelVeeStore
+ * @mi_data: a #CamelVeeMessageInfoData
+ * @unused_by: (type CamelVeeFolder): a #CamelVeeFolder
*
- * FIXME Document me!
+ * A counter part of camel_vee_store_note_vuid_used(). Once the @unused_by
+ * claims the @mi_data is not used by it anymore, and neither any other
+ * virtual folder is using it, then the Unmatched folder will have it added.
*
* Since: 3.6
**/
@@ -1027,8 +1036,13 @@ vee_store_rebuild_unmatched_folder (CamelSession *session,
/**
* camel_vee_store_rebuild_unmatched_folder:
+ * @vstore: a #CamelVeeStore
+ * @cancellable: optional #GCancellable object, or %NULL
+ * @error: return location for a #GError, or %NULL
*
- * FIXME Document me!
+ * Let's the @vstore know to rebuild the Unmatched folder. This is done
+ * as a separate job, when the @cancellable is %NULL, otherwise it's run
+ * synchronously.
*
* Since: 3.6
**/
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
