[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, 9 Dec 2016 09:34:25 +0000 (UTC)
commit e4a9b184b086c965db61341d9dde5c5bfcc4b50b
Author: Milan Crha <mcrha redhat com>
Date: Fri Dec 9 10:34:00 2016 +0100
Fix some of the gtk-doc warnings in Camel
src/camel/camel-html-parser.c | 2 +-
src/camel/camel-mime-parser.c | 2 +-
src/camel/camel-sexp.h | 1 +
src/camel/camel-store.h | 2 +
src/camel/camel-stream-filter.c | 6 +-
src/camel/camel-stream.c | 1 +
src/camel/camel-utf8.c | 73 +++++++------
src/camel/camel-vee-data-cache.c | 100 ++++++++++++-----
src/camel/camel-vee-folder.c | 116 ++++++++++++-------
src/camel/camel-vee-folder.h | 6 +-
src/camel/camel-vee-summary.c | 14 ++-
src/camel/providers/imapx/camel-imapx-search.c | 2 +-
src/camel/providers/local/camel-local-summary.c | 12 +-
src/camel/providers/local/camel-maildir-summary.c | 11 +-
src/camel/providers/local/camel-mbox-summary.c | 7 +-
src/camel/providers/local/camel-mh-summary.c | 7 +-
.../providers/nntp/camel-nntp-store-summary.c | 10 +-
src/camel/providers/pop3/camel-pop3-stream.c | 7 +-
18 files changed, 243 insertions(+), 136 deletions(-)
---
diff --git a/src/camel/camel-html-parser.c b/src/camel/camel-html-parser.c
index 901b879..5a83b7f 100644
--- a/src/camel/camel-html-parser.c
+++ b/src/camel/camel-html-parser.c
@@ -94,7 +94,7 @@ camel_html_parser_init (CamelHTMLParser *parser)
*
* Create a new CamelHTMLParser object.
*
- * Returns: A new CamelHTMLParser widget.
+ * Returns: (transfer full): A new #CamelHTMLParser object
**/
CamelHTMLParser *
camel_html_parser_new (void)
diff --git a/src/camel/camel-mime-parser.c b/src/camel/camel-mime-parser.c
index b5f9eed..c2c0c08 100644
--- a/src/camel/camel-mime-parser.c
+++ b/src/camel/camel-mime-parser.c
@@ -231,7 +231,7 @@ camel_mime_parser_init (CamelMimeParser *parser)
*
* Create a new CamelMimeParser object.
*
- * Returns: (transfer full): A new CamelMimeParser widget.
+ * Returns: (transfer full): A new #CamelMimeParser object
**/
CamelMimeParser *
camel_mime_parser_new (void)
diff --git a/src/camel/camel-sexp.h b/src/camel/camel-sexp.h
index f400d7d..cbb9f02 100644
--- a/src/camel/camel-sexp.h
+++ b/src/camel/camel-sexp.h
@@ -124,6 +124,7 @@ typedef CamelSExpResult *
/**
* CamelSExpIFunc:
+ * @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_ifunction()
diff --git a/src/camel/camel-store.h b/src/camel/camel-store.h
index 5c0c88b..e821ffb 100644
--- a/src/camel/camel-store.h
+++ b/src/camel/camel-store.h
@@ -98,6 +98,8 @@ G_BEGIN_DECLS
/**
* CamelStoreError:
+ * @CAMEL_STORE_ERROR_INVALID: an invalid store operation had been requested
+ * @CAMEL_STORE_ERROR_NO_FOLDER: requested operation cannot be performed with the given folder
*
* Since: 2.32
**/
diff --git a/src/camel/camel-stream-filter.c b/src/camel/camel-stream-filter.c
index 9ef6df5..873cfa5 100644
--- a/src/camel/camel-stream-filter.c
+++ b/src/camel/camel-stream-filter.c
@@ -418,10 +418,12 @@ camel_stream_filter_init (CamelStreamFilter *stream)
/**
* camel_stream_filter_new:
+ * @source: a #CamelStream to filter
*
- * Create a new #CamelStreamFilter object.
+ * Create a new #CamelStreamFilter object. The @source stream
+ * is referenced, thus the caller can unref it, if not needed.
*
- * Returns: a new #CamelStreamFilter object.
+ * Returns: (transfer full): a new #CamelStreamFilter object.
*
* Since: 2.32
**/
diff --git a/src/camel/camel-stream.c b/src/camel/camel-stream.c
index 67d6164..b053106 100644
--- a/src/camel/camel-stream.c
+++ b/src/camel/camel-stream.c
@@ -633,6 +633,7 @@ camel_stream_eos (CamelStream *stream)
* camel_stream_write_string:
* @stream: a #CamelStream object
* @string: a string
+ * @cancellable: optional #GCancellable object, or %NULL
* @error: return location for a #GError, or %NULL
*
* Writes the string to the stream.
diff --git a/src/camel/camel-utf8.c b/src/camel/camel-utf8.c
index ce8b1d4..fd1ba91 100644
--- a/src/camel/camel-utf8.c
+++ b/src/camel/camel-utf8.c
@@ -29,8 +29,8 @@
* @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.
+ * Output a 32 bit unicode character as UTF-8 octets. At most 4 octets will
+ * be written to @ptr. The @ptr will be advanced to the next character position.
**/
void
camel_utf8_putc (guchar **ptr,
@@ -60,14 +60,14 @@ camel_utf8_putc (guchar **ptr,
/**
* camel_utf8_getc:
- * @ptr: (inout): a pointer to read the characted from
+ * @ptr: (inout): a pointer to read the character from
*
- * Get a Unicode character from a utf8 stream. @ptr will be advanced
+ * Get a Unicode character from a UTF-8 stream. @ptr will be advanced
* to the next character position. Invalid utf8 characters will be
- * silently skipped. @ptr should point to a NUL terminated array.
+ * silently skipped. The @ptr should point to a NUL terminated array.
*
- * Returns: The next Unicode character. @ptr will be advanced to
- * the next character always.
+ * Returns: The next Unicode character. The @ptr will be advanced to
+ * the next character always.
**/
guint32
camel_utf8_getc (const guchar **ptr)
@@ -108,16 +108,16 @@ loop:
/**
* camel_utf8_getc_limit:
- * @ptr:
- * @end: must not be NULL.
+ * @ptr: (inout): a pointer to read the character from
+ * @end: upper limit for the read, must not be %NULL
*
- * Get the next utf8 gchar at @ptr, and return it, advancing @ptr to
- * the next character. If @end is reached before a full utf8
+ * Get the next UTF-8 gchar at @ptr, and return it, advancing @ptr to
+ * the next character. If @end is reached before a full UTF-8
* character can be read, then the invalid Unicode gchar 0xffff is
* returned as a sentinel (Unicode 3.1, section 2.7), and @ptr is not
* advanced.
*
- * Returns: The next utf8 char, or 0xffff.
+ * Returns: The next UTF-8 char, or 0xffff.
**/
guint32
camel_utf8_getc_limit (const guchar **ptr,
@@ -187,14 +187,15 @@ static const guchar utf7_rank[256] = {
/**
* camel_utf7_utf8:
- * @ptr:
+ * @ptr: a UTF-7 string to convert
*
- * Convert a modified utf7 string to utf8. If the utf7 string
+ * Convert a modified UTF-7 string to UTF-8. If the UTF-7 string
* contains 8 bit characters, they are treated as iso-8859-1.
*
- * The IMAP rules [rfc2060] are used in the utf7 encoding.
+ * The IMAP rules [rfc2060] are used in the UTF-7 encoding.
*
- * Returns: The converted string.
+ * Returns: (transfer full): The converted string. Free it with g_free(),
+ * when no longer needed.
**/
gchar *
camel_utf7_utf8 (const gchar *ptr)
@@ -269,13 +270,14 @@ static void utf7_closeb64 (GString *out, guint32 v, guint32 i)
/**
* camel_utf8_utf7:
- * @ptr:
+ * @ptr: a UTF-8 string to convert
*
- * Convert a utf8 string to a modified utf7 format.
+ * Convert a UTF-8 string to a modified UTF-7 format.
*
- * The IMAP rules [rfc2060] are used in the utf7 encoding.
+ * The IMAP rules [rfc2060] are used in the UTF-7 encoding.
*
- * Returns:
+ * Returns: (transfer full): The converted string. Free it with g_free(),
+ * when no longer needed.
**/
gchar *
camel_utf8_utf7 (const gchar *ptr)
@@ -327,24 +329,25 @@ camel_utf8_utf7 (const gchar *ptr)
/**
* camel_utf8_ucs2:
- * @ptr:
+ * @ptr: a UTF-8 string to convert
*
- * Convert a utf8 string into a ucs2 one. The ucs string will be in
- * network byte order, and terminated with a 16 bit NULL.
+ * Convert a UTF-8 string into a ucs2 one. The ucs string will be in
+ * network byte order, and terminated with a 16-bit %NULL.
*
- * Returns:
+ * Returns: (transfer full): The converted string. Free it with g_free(),
+ * when no longer needed.
**/
gchar *
-camel_utf8_ucs2 (const gchar *pptr)
+camel_utf8_ucs2 (const gchar *ptr)
{
GByteArray *work = g_byte_array_new ();
guint32 c;
gchar *out;
- const guchar *ptr = (const guchar *) pptr;
+ const guchar *uptr = (const guchar *) ptr;
/* what if c is > 0xffff ? */
- while ((c = camel_utf8_getc (&ptr))) {
+ while ((c = camel_utf8_getc (&uptr))) {
guint16 s = g_htons (c);
g_byte_array_append (work, (guchar *) &s, 2);
@@ -360,12 +363,13 @@ camel_utf8_ucs2 (const gchar *pptr)
/**
* camel_ucs2_utf8:
- * @ptr:
+ * @ptr: a ucs2 string to convert
*
- * Convert a ucs2 string into a utf8 one. The ucs2 string is treated
- * as network byte ordered, and terminated with a 16 bit NUL.
+ * Convert a ucs2 string into a UTF-8 one. The ucs2 string is treated
+ * as network byte ordered, and terminated with a 16-bit %NULL.
*
- * Returns:
+ * Returns: (transfer full): The converted string. Free it with g_free(),
+ * when no longer needed.
**/
gchar *
camel_ucs2_utf8 (const gchar *ptr)
@@ -386,10 +390,13 @@ camel_ucs2_utf8 (const gchar *ptr)
/**
* camel_utf8_make_valid:
- * @text:
+ * @text: a text to make valid
*
* Ensures the returned text will be valid UTF-8 string, with incorrect letters
- * changed to question marks. Returned pointer should be freed with g_free.
+ * changed to question marks.
+ *
+ * Returns: (transfer full): Valid UTF-8 string, with replaced incorrect letters.
+ * Free it with g_free(), when no longer needed.
*
* Since: 2.26
**/
diff --git a/src/camel/camel-vee-data-cache.c b/src/camel/camel-vee-data-cache.c
index b3567e8..83b6854 100644
--- a/src/camel/camel-vee-data-cache.c
+++ b/src/camel/camel-vee-data-cache.c
@@ -125,8 +125,13 @@ vee_subfolder_data_hash_folder (CamelFolder *folder,
/**
* camel_vee_subfolder_data_new:
+ * @folder: a #CamelFolder for which create the object
*
- * FIXME Document me!
+ * Creates a new #CamelVeeSubfolderData object for the given @folder.
+ * The @folder is referenced for later use.
+ *
+ * Returns: (transfer full): a new #CamelVeeSubfolderData. Use g_object_unref()
+ * to unref it, when no longer needed.
*
* Since: 3.6
**/
@@ -151,10 +156,9 @@ camel_vee_subfolder_data_new (CamelFolder *folder)
/**
* camel_vee_subfolder_data_get_folder:
+ * @data: a CamelVeeSubfolderData
*
- * FIXME Document me!
- *
- * Returns: (transfer none):
+ * Returns: (transfer none): a #CamelFolder to which this @data was created
*
* Since: 3.6
**/
@@ -168,8 +172,9 @@ camel_vee_subfolder_data_get_folder (CamelVeeSubfolderData *data)
/**
* camel_vee_subfolder_data_get_folder_id:
+ * @data: a CamelVeeSubfolderData
*
- * FIXME Document me!
+ * Returns: (transfer none): a folder ID for this subfolder @data
*
* Since: 3.6
**/
@@ -251,8 +256,12 @@ camel_vee_message_info_data_init (CamelVeeMessageInfoData *data)
/**
* camel_vee_message_info_data_new:
+ * @subfolder_data: a #CamelVeeSubfolderData
+ * @orig_message_uid: original message info's UID
*
- * FIXME Document me!
+ * Returns: (transfer full): a new #CamelVeeMessageInfoData which references
+ * message info with UID @orig_message_uid froma folder managed by @subfolder_data.
+ * Unref the returned object with g_object_unref(), when no longer needed.
*
* Since: 3.6
**/
@@ -279,10 +288,10 @@ camel_vee_message_info_data_new (CamelVeeSubfolderData *subfolder_data,
/**
* camel_vee_message_info_data_get_subfolder_data:
+ * @data: a CamelVeeMessageInfoData
*
- * FIXME Document me!
- *
- * Returns: (transfer none):
+ * Returns: (transfer none): A #CamelVeeSubfolderData for which
+ * the @data had been created.
*
* Since: 3.6
**/
@@ -296,8 +305,10 @@ camel_vee_message_info_data_get_subfolder_data (CamelVeeMessageInfoData *data)
/**
* camel_vee_message_info_data_get_orig_message_uid:
+ * @data: a CamelVeeMessageInfoData
*
- * FIXME Document me!
+ * Returns: (transfer none): The original message info's UID, for which
+ * the @data had been created.
*
* Since: 3.6
**/
@@ -311,8 +322,10 @@ camel_vee_message_info_data_get_orig_message_uid (CamelVeeMessageInfoData *data)
/**
* camel_vee_message_info_data_get_vee_message_uid:
+ * @data: a CamelVeeMessageInfoData
*
- * FIXME Document me!
+ * Returns: (transfer none): Message UID corresponding to this virtual
+ * message info @data.
*
* Since: 3.6
**/
@@ -441,7 +454,8 @@ camel_vee_data_cache_init (CamelVeeDataCache *data_cache)
/**
* camel_vee_data_cache_new:
*
- * FIXME Document me!
+ * Returns: (transfer full): a new #CamelVeeDataCache; unref it
+ * with g_object_unref(), when no longer needed.
*
* Since: 3.6
**/
@@ -453,8 +467,13 @@ camel_vee_data_cache_new (void)
/**
* camel_vee_data_cache_add_subfolder:
+ * @data_cache: a #CamelVeeDataCache
+ * @subfolder: a #CamelFolder
*
- * FIXME Document me!
+ * Adds the @subfolder to the @data_cache to be tracked by it. The @subfolder
+ * is referenced for later use. The function does nothing when the @subfolder
+ * is already in the @data_cache. The subfolders can be removed with
+ * camel_vee_data_cache_remove_subfolder().
*
* Since: 3.6
**/
@@ -549,8 +568,13 @@ remove_orig_by_folder_cb (gpointer key,
/**
* camel_vee_data_cache_remove_subfolder:
+ * @data_cache: a #CamelVeeDataCache
+ * @subfolder: a #CamelFolder to remove
*
- * FIXME Document me!
+ * Removes given @subfolder from the @data_cache, which had been
+ * previously added with camel_vee_data_cache_add_subfolder().
+ * The function does nothing, when the @subfolder is not part
+ * of the @data_cache.
*
* Since: 3.6
**/
@@ -574,10 +598,13 @@ camel_vee_data_cache_remove_subfolder (CamelVeeDataCache *data_cache,
/**
* camel_vee_data_cache_get_subfolder_data:
+ * @data_cache: a #CamelVeeDataCache
+ * @folder: a #CamelFolder for which to return subfolder data
*
- * FIXME Document me!
+ * Returns a #CamelVeeSubfolderData for the given @folder.
*
- * Returns: (transfer full):
+ * Returns: (transfer full): a referenced #CamelVeeSubfolderData; unref it
+ * with g_object_unref(), when no longer needed.
*
* Since: 3.6
**/
@@ -607,10 +634,13 @@ camel_vee_data_cache_get_subfolder_data (CamelVeeDataCache *data_cache,
/**
* camel_vee_data_cache_contains_message_info_data:
+ * @data_cache: a #CamelVeeDataCache
+ * @folder: a #CamelFolder to which the @orig_message_uid belongs
+ * @orig_message_uid: a message UID from the @folder to check
*
- * Returns whether data_cache contains certain UID for certain folder;
- * instead of camel_vee_data_cache_get_message_info_data() only
- * returns FALSE if not, while camel_vee_data_cache_get_message_info_data()
+ * Returns whether data_cache contains given @orig_message_uid for the given @folder.
+ * Unlike camel_vee_data_cache_get_message_info_data(), this only
+ * returns %FALSE if not, while camel_vee_data_cache_get_message_info_data()
* auto-adds it to data_cache.
*
* Since: 3.6
@@ -644,10 +674,17 @@ camel_vee_data_cache_contains_message_info_data (CamelVeeDataCache *data_cache,
/**
* camel_vee_data_cache_get_message_info_data:
+ * @data_cache: a #CamelVeeDataCache
+ * @folder: a #CamelFolder to which the @orig_message_uid belongs
+ * @orig_message_uid: a message UID from the @folder to return
*
- * FIXME Document me!
+ * Returns a referenced #CamelVeeMessageInfoData referencing the given @folder
+ * and @orig_message_uid. If it's not part of the @data_cache, then it is
+ * created and auto-added. Use camel_vee_data_cache_contains_message_info_data()
+ * when you only want to check the existence, without adding it to the @data_cache.
*
- * Returns: (transfer full):
+ * Returns: (transfer full): a referenced #CamelVeeMessageInfoData; unref it
+ * with g_object_unref(), when no longer needed.
*
* Since: 3.6
**/
@@ -708,10 +745,13 @@ camel_vee_data_cache_get_message_info_data (CamelVeeDataCache *data_cache,
/**
* camel_vee_data_cache_get_message_info_data_by_vuid:
+ * @data_cache: a #CamelVeeDataCache
+ * @vee_message_uid: a message UID in the virtual folder
*
- * FIXME Document me!
- *
- * Returns: (transfer full):
+ * Returns: (transfer full) (nullable): a referenced #CamelVeeMessageInfoData,
+ * which corresponds to the given @vee_message_uid, or %NULL, when no such
+ * message info with that virtual UID exists. Unref it with g_object_unref(),
+ * when no longer needed.
*
* Since: 3.6
**/
@@ -766,8 +806,12 @@ cvdc_foreach_mi_data_cb (gpointer key,
/**
* camel_vee_data_cache_foreach_message_info_data:
- * @func: (scope call) (closure user_data):
- * FIXME Document me!
+ * @data_cache: a #CamelVeeDataCache
+ * @fromfolder: a #CamelFolder
+ * @func: (scope call) (closure user_data): a #CamelForeachInfoData function to call
+ * @user_data: user data to pass to the @func
+ *
+ * Calls the @func for each message info data from the given @fromfolder
*
* Since: 3.6
**/
@@ -795,8 +839,10 @@ camel_vee_data_cache_foreach_message_info_data (CamelVeeDataCache *data_cache,
/**
* camel_vee_data_cache_remove_message_info_data:
+ * @data_cache: a #CamelVeeDataCache
+ * @mi_data: a #CamelVeeMessageInfoData to remove
*
- * FIXME Document me!
+ * Removes given @mi_data from the @data_cache.
*
* Since: 3.6
**/
diff --git a/src/camel/camel-vee-folder.c b/src/camel/camel-vee-folder.c
index bdf1578..2555b14 100644
--- a/src/camel/camel-vee-folder.c
+++ b/src/camel/camel-vee-folder.c
@@ -1334,9 +1334,8 @@ camel_vee_folder_get_flags (CamelVeeFolder *vf)
* @full: the full path to the vfolder.
* @flags: flags of some kind
*
- * Create a new CamelVeeFolder object.
- *
- * Returns: A new CamelVeeFolder widget.
+ * Returns: (transfer full): A new @CamelVeeFolder object. Unref it
+ * with g_object_unref() when no longer needed.
**/
CamelFolder *
camel_vee_folder_new (CamelStore *parent_store,
@@ -1371,17 +1370,29 @@ camel_vee_folder_new (CamelStore *parent_store,
return (CamelFolder *) vf;
}
+/**
+ * camel_vee_folder_set_expression:
+ * @vfolder: a #CamelVeeFolder
+ * @expression: an SExp expression to set
+ *
+ * Sets an SExp expression to be used for this @vfolder
+ *
+ * Since: 3.6
+ **/
void
camel_vee_folder_set_expression (CamelVeeFolder *vfolder,
- const gchar *expr)
+ const gchar *expression)
{
- CAMEL_VEE_FOLDER_GET_CLASS (vfolder)->set_expression (vfolder, expr);
+ g_return_if_fail (CAMEL_IS_VEE_FOLDER (vfolder));
+
+ CAMEL_VEE_FOLDER_GET_CLASS (vfolder)->set_expression (vfolder, expression);
}
/**
* camel_vee_folder_get_expression:
+ * @vfolder: a #CamelVeeFolder
*
- * FIXME Document me!
+ * Returns: (transfer none): a SExp expression used for this @vfolder
*
* Since: 3.6
**/
@@ -1395,8 +1406,9 @@ camel_vee_folder_get_expression (CamelVeeFolder *vfolder)
/**
* camel_vee_folder_add_folder:
- * @vfolder: Virtual Folder object
+ * @vfolder: a #CamelVeeFolder
* @subfolder: source CamelFolder to add to @vfolder
+ * @cancellable: optional #GCancellable object, or %NULL
*
* Adds @subfolder as a source folder to @vfolder.
**/
@@ -1445,8 +1457,9 @@ camel_vee_folder_add_folder (CamelVeeFolder *vfolder,
/**
* camel_vee_folder_remove_folder:
- * @vfolder: Virtual Folder object
+ * @vfolder: a #CamelVeeFolder
* @subfolder: source CamelFolder to remove from @vfolder
+ * @cancellable: optional #GCancellable object, or %NULL
*
* Removed the source folder, @subfolder, from the virtual folder, @vfolder.
**/
@@ -1486,7 +1499,7 @@ camel_vee_folder_remove_folder (CamelVeeFolder *vfolder,
/**
* camel_vee_folder_rebuild_folder:
- * @vfolder: Virtual Folder object
+ * @vfolder: a #CamelVeeFolder
* @subfolder: source CamelFolder to add to @vfolder
* @cancellable: optional #GCancellable object, or %NULL
*
@@ -1513,32 +1526,36 @@ remove_folders (CamelFolder *folder,
/**
* camel_vee_folder_set_folders:
- * @vf:
- * @folders: (element-type CamelFolder) (transfer none):
+ * @vfolder: a #CamelVeeFolder
+ * @folders: (element-type CamelFolder) (transfer none): a #GList of #CamelFolder to add
+ * @cancellable: optional #GCancellable object, or %NULL
*
* Set the whole list of folder sources on a vee folder.
**/
void
-camel_vee_folder_set_folders (CamelVeeFolder *vf,
+camel_vee_folder_set_folders (CamelVeeFolder *vfolder,
GList *folders,
GCancellable *cancellable)
{
- CamelVeeFolderPrivate *p = CAMEL_VEE_FOLDER_GET_PRIVATE (vf);
- GHashTable *remove = g_hash_table_new (NULL, NULL);
+ GHashTable *remove;
GList *l, *to_add = NULL;
CamelFolder *folder;
+ g_return_if_fail (CAMEL_IS_VEE_FOLDER (vfolder));
+
+ remove = g_hash_table_new (NULL, NULL);
+
/* setup a table of all folders we have currently */
- g_rec_mutex_lock (&vf->priv->subfolder_lock);
- l = p->subfolders;
+ g_rec_mutex_lock (&vfolder->priv->subfolder_lock);
+ l = vfolder->priv->subfolders;
while (l) {
g_hash_table_insert (remove, l->data, l->data);
g_object_ref (l->data);
l = l->next;
}
- g_rec_mutex_unlock (&vf->priv->subfolder_lock);
+ g_rec_mutex_unlock (&vfolder->priv->subfolder_lock);
- camel_folder_freeze (CAMEL_FOLDER (vf));
+ camel_folder_freeze (CAMEL_FOLDER (vfolder));
/* if we already have the folder, ignore it, otherwise mark to add it */
l = folders;
@@ -1553,25 +1570,28 @@ camel_vee_folder_set_folders (CamelVeeFolder *vf,
}
/* first remove any we still have */
- g_hash_table_foreach (remove, (GHFunc) remove_folders, vf);
+ g_hash_table_foreach (remove, (GHFunc) remove_folders, vfolder);
g_hash_table_destroy (remove);
/* then add those new */
for (l = to_add; l; l = l->next) {
- camel_vee_folder_add_folder (vf, l->data, cancellable);
+ camel_vee_folder_add_folder (vfolder, l->data, cancellable);
}
g_list_free_full (to_add, g_object_unref);
- camel_folder_thaw (CAMEL_FOLDER (vf));
+ camel_folder_thaw (CAMEL_FOLDER (vfolder));
}
/**
* camel_vee_folder_add_vuid:
- * @vfolder:
- * @mi_data: (type CamelVeeMessageInfoData):
- * @changes:
+ * @vfolder: a #CamelVeeFolder
+ * @mi_data: a #CamelVeeMessageInfoData to add
+ * @changes: (nullable): an optional #CamelFolderChangeInfo to update with the made change, or %NULL
*
- * FIXME Document me!
+ * Adds the @mi_data to the @vfolder. The @changes can be
+ * updated with the made change and later used to notify others
+ * with came_folder_changed() on the @vfolder. This can be used
+ * only for the Unmatched folder.
*
* Since: 3.6
**/
@@ -1621,11 +1641,14 @@ camel_vee_folder_add_vuid (CamelVeeFolder *vfolder,
/**
* camel_vee_folder_remove_vuid:
- * @vfolder:
- * @mi_data: (type CamelVeeMessageInfoData):
- * @changes:
+ * @vfolder: a #CamelVeeFolder
+ * @mi_data: a #CamelVeeMessageInfoData to remove
+ * @changes: (nullable): an optional #CamelFolderChangeInfo to update with the made change, or %NULL
*
- * FIXME Document me!
+ * Removes given @mi_data from the @vfolder. The @changes can be
+ * updated with the made change and later used to notify others
+ * with came_folder_changed() on the @vfolder. This can be used
+ * only for the Unmatched folder.
*
* Since: 3.6
**/
@@ -1680,14 +1703,15 @@ camel_vee_folder_remove_vuid (CamelVeeFolder *vfolder,
/**
* camel_vee_folder_get_location:
- * @vf:
- * @vinfo:
- * @realuid: if not NULL, set to the uid of the real message, must be
- * g_free'd by caller.
+ * @vf: a #CamelVeeFolder
+ * @vinfo: a #CamelVeeMessageInfo to search for
+ * @realuid: (out) (transfer full) (nullable): if not %NULL, set to the UID of the real message info
*
- * Find the real folder (and uid)
+ * Find the real folder (and message info UID) for the given @vinfo.
+ * When the @realuid is not %NULL and it's set, then use g_free() to
+ * free it, when no longer needed.
*
- * Returns: (transfer none):
+ * Returns: (transfer none): a real (not virtual) #CamelFolder, which the @vinfo is for.
**/
CamelFolder *
camel_vee_folder_get_location (CamelVeeFolder *vf,
@@ -1725,15 +1749,16 @@ camel_vee_folder_get_location (CamelVeeFolder *vf,
/**
* camel_vee_folder_get_vee_uid_folder:
+ * @vfolder: a #CamelVeeFolder
+ * @vee_message_uid: a virtual message info UID
*
- * FIXME Document me!
- *
- * Returns: (transfer none):
+ * Returns: (transfer none) (nullable): a #CamelFolder to which the @vee_message_info
+ * belongs, or %NULL, when it could not be found.
*
* Since: 3.6
**/
CamelFolder *
-camel_vee_folder_get_vee_uid_folder (CamelVeeFolder *vf,
+camel_vee_folder_get_vee_uid_folder (CamelVeeFolder *vfolder,
const gchar *vee_message_uid)
{
CamelFolder *res;
@@ -1741,12 +1766,12 @@ camel_vee_folder_get_vee_uid_folder (CamelVeeFolder *vf,
CamelVeeMessageInfoData *mi_data;
CamelVeeSubfolderData *sf_data;
- g_return_val_if_fail (CAMEL_IS_VEE_FOLDER (vf), NULL);
+ g_return_val_if_fail (CAMEL_IS_VEE_FOLDER (vfolder), NULL);
g_return_val_if_fail (vee_message_uid, NULL);
res = NULL;
- data_cache = vee_folder_get_data_cache (vf);
+ data_cache = vee_folder_get_data_cache (vfolder);
g_return_val_if_fail (data_cache != NULL, NULL);
mi_data = camel_vee_data_cache_get_message_info_data_by_vuid (data_cache, vee_message_uid);
@@ -1761,8 +1786,11 @@ camel_vee_folder_get_vee_uid_folder (CamelVeeFolder *vf,
/**
* camel_vee_folder_set_auto_update:
+ * @vfolder: a #CamelVeeFolder
+ * @auto_update: a value to set
*
- * FIXME Document me!
+ * Sets whether the @vfolder can automatically update when of its
+ * subfolders changes.
*
* Since: 3.6
**/
@@ -1782,8 +1810,10 @@ camel_vee_folder_set_auto_update (CamelVeeFolder *vfolder,
/**
* camel_vee_folder_get_auto_update:
+ * @vfolder: a #CamelVeeFolder
*
- * FIXME Document me!
+ * Returns: whether the @vfolder can automatically update when any
+ * of its subfolders changes.
*
* Since: 3.6
**/
diff --git a/src/camel/camel-vee-folder.h b/src/camel/camel-vee-folder.h
index bee2eed..99ecb55 100644
--- a/src/camel/camel-vee-folder.h
+++ b/src/camel/camel-vee-folder.h
@@ -98,7 +98,7 @@ guint32 camel_vee_folder_get_flags (CamelVeeFolder *vf);
CamelFolder * camel_vee_folder_get_location (CamelVeeFolder *vf,
const CamelVeeMessageInfo *vinfo,
gchar **realuid);
-CamelFolder * camel_vee_folder_get_vee_uid_folder (CamelVeeFolder *vf,
+CamelFolder * camel_vee_folder_get_vee_uid_folder (CamelVeeFolder *vfolder,
const gchar *vee_message_uid);
void camel_vee_folder_set_auto_update (CamelVeeFolder *vfolder,
gboolean auto_update);
@@ -109,7 +109,7 @@ void camel_vee_folder_add_folder (CamelVeeFolder *vfolder,
void camel_vee_folder_remove_folder (CamelVeeFolder *vfolder,
CamelFolder *subfolder,
GCancellable *cancellable);
-void camel_vee_folder_set_folders (CamelVeeFolder *vf,
+void camel_vee_folder_set_folders (CamelVeeFolder *vfolder,
GList *folders,
GCancellable *cancellable);
void camel_vee_folder_add_vuid (CamelVeeFolder *vfolder,
@@ -123,7 +123,7 @@ void camel_vee_folder_rebuild_folder (CamelVeeFolder *vfolder,
CamelFolder *subfolder,
GCancellable *cancellable);
void camel_vee_folder_set_expression (CamelVeeFolder *vfolder,
- const gchar *expr);
+ const gchar *expression);
const gchar * camel_vee_folder_get_expression (CamelVeeFolder *vfolder);
void camel_vee_folder_ignore_next_changed_event
diff --git a/src/camel/camel-vee-summary.c b/src/camel/camel-vee-summary.c
index 11e6a4e..c75f01a 100644
--- a/src/camel/camel-vee-summary.c
+++ b/src/camel/camel-vee-summary.c
@@ -165,10 +165,15 @@ get_uids_for_subfolder (gpointer key,
/**
* camel_vee_summary_get_uids_for_subfolder:
+ * @summary: a #CamelVeeSummary
+ * @subfolder: a #CamelFolder
*
- * FIXME Document me!
+ * Returns a hash table of all virtual message info UID-s known to the @summary.
+ * The key of the hash table is the virtual message info UID, the value is
+ * only the number 1.
*
- * Returns: (element-type utf8 utf8) (transfer container):
+ * Returns: (element-type utf8 gint) (transfer container): a #GHashTable with
+ * all the virtual mesasge info UID-s knwn to the @summary.
*
* Since: 3.6
**/
@@ -254,8 +259,11 @@ camel_vee_summary_add (CamelVeeSummary *summary,
/**
* camel_vee_summary_remove:
+ * @summary: a #CamelVeeSummary
+ * @vuid: a virtual message info UID to remove
+ * @subfolder: a #CamelFolder to which @vuid belongs
*
- * FIXME Document me!
+ * Removes the given @vuid of the @subfolder from the @summary.
*
* Since: 3.6
**/
diff --git a/src/camel/providers/imapx/camel-imapx-search.c b/src/camel/providers/imapx/camel-imapx-search.c
index f06215b..e24d1e8 100644
--- a/src/camel/providers/imapx/camel-imapx-search.c
+++ b/src/camel/providers/imapx/camel-imapx-search.c
@@ -670,7 +670,7 @@ camel_imapx_search_ref_store (CamelIMAPXSearch *search)
/**
* camel_imapx_search_set_store:
* @search: a #CamelIMAPXSearch
- * @imapx_server: a #CamelIMAPXStore, or %NULL
+ * @imapx_store: a #CamelIMAPXStore, or %NULL
*
* Sets a #CamelIMAPXStore to use for server-side searches. Generally
* this is set for the duration of a single search when online, and then
diff --git a/src/camel/providers/local/camel-local-summary.c b/src/camel/providers/local/camel-local-summary.c
index 1d0a2c3..2566643 100644
--- a/src/camel/providers/local/camel-local-summary.c
+++ b/src/camel/providers/local/camel-local-summary.c
@@ -372,13 +372,13 @@ camel_local_summary_add (CamelLocalSummary *cls,
/**
* camel_local_summary_write_headers:
- * @fd:
- * @headers:
- * @xevline:
- * @status:
- * @xstatus:
+ * @fd: a file descriptor to write to
+ * @headers: a #CamelNameValueArray with headers to write
+ * @xevline: (nullable): an optional value of X-Evolution header to add
+ * @status: (nullable): an optional value of Status header to add
+ * @xstatus: (nullable): an optional value of X-Status header to add
*
- * Write a bunch of headers to the file @fd. IF xevline is non NULL, then
+ * Write a bunch of headers to the file @fd. If xevline is non NULL, then
* an X-Evolution header line is created at the end of all of the headers.
* If @status is non NULL, then a Status header line is also written.
* The headers written are termianted with a blank line.
diff --git a/src/camel/providers/local/camel-maildir-summary.c
b/src/camel/providers/local/camel-maildir-summary.c
index 7b240f6..c6a929e 100644
--- a/src/camel/providers/local/camel-maildir-summary.c
+++ b/src/camel/providers/local/camel-maildir-summary.c
@@ -164,14 +164,17 @@ camel_maildir_summary_init (CamelMaildirSummary *maildir_summary)
/**
* camel_maildir_summary_new:
* @folder: parent folder.
- * @index: Index if one is reqiured.
+ * @maildirdir: a maildir directory for the new summary
+ * @index: (nullable): an optional #CamelIndex to use, or %NULL
*
* Create a new CamelMaildirSummary object.
*
- * Returns: A new #CamelMaildirSummary object.
+ * Returns: (transfer full): A new #CamelMaildirSummary object
**/
-CamelMaildirSummary
-*camel_maildir_summary_new(struct _CamelFolder *folder, const gchar *maildirdir, CamelIndex *index)
+CamelMaildirSummary *
+camel_maildir_summary_new (struct _CamelFolder *folder,
+ const gchar *maildirdir,
+ CamelIndex *index)
{
CamelMaildirSummary *o;
diff --git a/src/camel/providers/local/camel-mbox-summary.c b/src/camel/providers/local/camel-mbox-summary.c
index 0ce4d4f..b0d94cd 100644
--- a/src/camel/providers/local/camel-mbox-summary.c
+++ b/src/camel/providers/local/camel-mbox-summary.c
@@ -146,10 +146,13 @@ camel_mbox_summary_init (CamelMboxSummary *mbox_summary)
/**
* camel_mbox_summary_new:
+ * @folder: a parent #CamelFolder
+ * @mbox_name: filename of the mbox
+ * @index: (nullable): an optional #CamelIndex to use, or %NULL
*
- * Create a new CamelMboxSummary object.
+ * Create a new #CamelMboxSummary object.
*
- * Returns: A new CamelMboxSummary widget.
+ * Returns: (transfer full): A new #CamelMboxSummary object
**/
CamelMboxSummary *
camel_mbox_summary_new (CamelFolder *folder,
diff --git a/src/camel/providers/local/camel-mh-summary.c b/src/camel/providers/local/camel-mh-summary.c
index 6c33a58..f3aa034 100644
--- a/src/camel/providers/local/camel-mh-summary.c
+++ b/src/camel/providers/local/camel-mh-summary.c
@@ -88,10 +88,13 @@ camel_mh_summary_init (CamelMhSummary *mh_summary)
/**
* camel_mh_summary_new:
+ * @folder: a parent #CamelFolder
+ * @mhdir: an MH directory for the new summary
+ * @index: (nullable): an optional #CamelIndex to use, or %NULL
*
- * Create a new CamelMhSummary object.
+ * Create a new #CamelMhSummary object.
*
- * Returns: A new #CamelMhSummary object.
+ * Returns: (transfer full): A new #CamelMhSummary object.
**/
CamelMhSummary *
camel_mh_summary_new (CamelFolder *folder,
diff --git a/src/camel/providers/nntp/camel-nntp-store-summary.c
b/src/camel/providers/nntp/camel-nntp-store-summary.c
index cacccce..a8e4fa4 100644
--- a/src/camel/providers/nntp/camel-nntp-store-summary.c
+++ b/src/camel/providers/nntp/camel-nntp-store-summary.c
@@ -75,7 +75,7 @@ camel_nntp_store_summary_init (CamelNNTPStoreSummary *nntp_store_summary)
*
* Create a new CamelNNTPStoreSummary object.
*
- * Returns: A new CamelNNTPStoreSummary widget.
+ * Returns: (transfer full): A new #CamelNNTPStoreSummary object
**/
CamelNNTPStoreSummary *
camel_nntp_store_summary_new (void)
@@ -85,16 +85,16 @@ camel_nntp_store_summary_new (void)
/**
* camel_nntp_store_summary_full_name:
- * @s:
- * @full_name:
+ * @s: a #CamelNNTPStoreSummary
+ * @full_name: a full name of the summary item to search for
*
* Retrieve a summary item by full name.
*
* The returned #CamelNNTPStoreInfo is referenced for thread-safety and should
* be unreferenced with camel_store_summary_info_unref() when finished with it.
*
- * Returns: The summary item, or NULL if the @full_name name
- * is not available.
+ * Returns: (transfer full) (nullable): The summary item, or %NULL if the @full_name name
+ * is not available.
**/
CamelNNTPStoreInfo *
camel_nntp_store_summary_full_name (CamelNNTPStoreSummary *s,
diff --git a/src/camel/providers/pop3/camel-pop3-stream.c b/src/camel/providers/pop3/camel-pop3-stream.c
index 69398e5..74bb11e 100644
--- a/src/camel/providers/pop3/camel-pop3-stream.c
+++ b/src/camel/providers/pop3/camel-pop3-stream.c
@@ -255,11 +255,12 @@ camel_pop3_stream_init (CamelPOP3Stream *is)
/**
* camel_pop3_stream_new:
+ * @source: a #CamelStream to operate on
*
- * Returns a NULL stream. A null stream is always at eof, and
- * always returns success for all reads and writes.
+ * Creates a new #CamelPOP3Stream which operates on the @source.
+ * The @source stream is referenced for later use.
*
- * Returns: the stream
+ * Returns: (transfer full): a new #CamelPOP3Stream
**/
CamelStream *
camel_pop3_stream_new (CamelStream *source)
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
