From: Richard Russon <rich@flatcap.org>
Date: Mon, 5 Feb 2018 15:46:54 +0000 (+0000)
Subject: doxygen fix comments
X-Git-Tag: neomutt-20180223~2^2~5
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=6b1ea9288944e34e9fc0a8fdb3f96d6f71e3b677;p=neomutt

doxygen fix comments
---

diff --git a/mutt/base64.c b/mutt/base64.c
index 2f77fadf0..352cbd48c 100644
--- a/mutt/base64.c
+++ b/mutt/base64.c
@@ -36,8 +36,8 @@
  *
  * | Function          | Description
  * | :---------------- | :-------------------------------------------------
- * | mutt_b64_encode() | Convert raw bytes to null-terminated base64 string
  * | mutt_b64_decode() | Convert null-terminated base64 string to raw bytes
+ * | mutt_b64_encode() | Convert raw bytes to null-terminated base64 string
  */
 
 #include "config.h"
diff --git a/mutt/charset.c b/mutt/charset.c
index 9088fcc6a..3e0e552e2 100644
--- a/mutt/charset.c
+++ b/mutt/charset.c
@@ -27,9 +27,9 @@
  *
  * | Data                | Description
  * | :------------------ | :--------------------------------------------------
- * | #Charset            | User's chosen character set
+ * | #AssumedCharset     | Encoding schemes for messages without indication
+ * | #Charset            | User's choice of character set
  * | #Charset_is_utf8    | Is the user's current character set utf-8?
- * | #lookup_charset     | Look for a preferred character set name
  * | #PreferredMIMENames | Lookup table of preferred charsets
  * | #ReplacementChar    | When a Unicode character can't be displayed, use this instead
  *
@@ -38,13 +38,14 @@
  * | mutt_ch_canonical_charset()      | Canonicalise the charset of a string
  * | mutt_ch_charset_lookup()         | Look for a replacement character set
  * | mutt_ch_check_charset()          | Does iconv understand a character set?
+ * | mutt_ch_choose()                 | Figure the best charset to encode a string
  * | mutt_ch_chscmp()                 | Are the names of two character sets equivalent?
- * | mutt_ch_convert_nonmime_string() | XXX
+ * | mutt_ch_convert_nonmime_string() | Try to convert a string using a list of character sets
  * | mutt_ch_convert_string()         | Convert a string between encodings
  * | mutt_ch_fgetconv()               | Convert a file's character set
- * | mutt_ch_fgetconvs()              | Convert a file's charset into a string buffer
  * | mutt_ch_fgetconv_close()         | Close an fgetconv handle
  * | mutt_ch_fgetconv_open()          | Prepare a file for charset conversion
+ * | mutt_ch_fgetconvs()              | Convert a file's charset into a string buffer
  * | mutt_ch_get_default_charset()    | Get the default character set
  * | mutt_ch_iconv()                  | Change the encoding of a string
  * | mutt_ch_iconv_lookup()           | Look for a replacement character set
@@ -53,7 +54,6 @@
  * | mutt_ch_lookup_remove()          | Remove all the character set lookups
  * | mutt_ch_set_charset()            | Update the records for a new character set
  * | mutt_ch_set_langinfo_charset()   | Set the user's choice of character set
- * | mutt_ch_choose()                 | Figure the best charset to encode a string
  */
 
 #include "config.h"
diff --git a/mutt/file.c b/mutt/file.c
index 471b2b0be..43c2c9497 100644
--- a/mutt/file.c
+++ b/mutt/file.c
@@ -34,8 +34,8 @@
  * | mutt_file_chmod_add_stat()    | Add permissions to a file
  * | mutt_file_chmod_rm()          | Remove permissions from a file
  * | mutt_file_chmod_rm_stat()     | Remove permissions from a file
- * | mutt_file_concatn_path()      | Concatenate directory and filename
  * | mutt_file_concat_path()       | Join a directory name and a filename
+ * | mutt_file_concatn_path()      | Concatenate directory and filename
  * | mutt_file_copy_bytes()        | Copy some content from one file to another
  * | mutt_file_copy_stream()       | Copy the contents of one file into another
  * | mutt_file_decrease_mtime()    | Decrease a file's modification time by 1 second
@@ -56,8 +56,8 @@
  * | mutt_file_sanitize_regex()    | Escape any regex-magic characters in a string
  * | mutt_file_set_mtime()         | Set the modification time of one file from another
  * | mutt_file_symlink()           | Create a symlink
- * | mutt_file_touch_atime()       | Set the access time to current time
  * | mutt_file_to_absolute_path()  | Convert relative filepath to an absolute path
+ * | mutt_file_touch_atime()       | Set the access time to current time
  * | mutt_file_unlink()            | Delete a file, carefully
  * | mutt_file_unlink_empty()      | Delete a file if it's empty
  * | mutt_file_unlock()            | Unlock a file previously locked by mutt_file_lock()
@@ -1262,7 +1262,6 @@ void mutt_file_unlink_empty(const char *path)
  * note on access(2) use: No dangling symlink problems here due to
  * mutt_file_fopen().
  */
-
 int mutt_file_rename(char *oldfile, char *newfile)
 {
   FILE *ofp = NULL, *nfp = NULL;
diff --git a/mutt/hash.c b/mutt/hash.c
index 290f9eba9..fc4a57201 100644
--- a/mutt/hash.c
+++ b/mutt/hash.c
@@ -26,20 +26,22 @@
  *
  * Hash table data structure.
  *
- * | Function                | Description
- * | :---------------------- | :---------------------------------------------------------
- * | mutt_hash_create()      | Create a new Hash table (with string keys)
- * | mutt_hash_delete()      | Remove an element from a Hash table
- * | mutt_hash_destroy()     | Destroy a hash table
- * | mutt_hash_find()        | Find the HashElem data in a Hash table element using a key
- * | mutt_hash_find_bucket() | Find the HashElem in a Hash table element using a key
- * | mutt_hash_find_elem()   | Find the HashElem in a Hash table element using a key
- * | mutt_hash_insert()      | Add a new element to the Hash table (with string keys)
- * | mutt_hash_int_create()  | Create a new Hash table (with integer keys)
- * | mutt_hash_int_delete()  | Remove an element from a Hash table
- * | mutt_hash_int_find()    | Find the HashElem data in a Hash table element using a key
- * | mutt_hash_int_insert()  | Add a new element to the Hash table (with integer keys)
- * | mutt_hash_walk()        | Iterate through all the HashElem's in a Hash table
+ * | Function                   | Description
+ * | :------------------------- | :---------------------------------------------------------
+ * | mutt_hash_create()         | Create a new Hash table (with string keys)
+ * | mutt_hash_delete()         | Remove an element from a Hash table
+ * | mutt_hash_destroy()        | Destroy a hash table
+ * | mutt_hash_find()           | Find the HashElem data in a Hash table element using a key
+ * | mutt_hash_find_bucket()    | Find the HashElem in a Hash table element using a key
+ * | mutt_hash_find_elem()      | Find the HashElem in a Hash table element using a key
+ * | mutt_hash_insert()         | Add a new element to the Hash table (with string keys)
+ * | mutt_hash_int_create()     | Create a new Hash table (with integer keys)
+ * | mutt_hash_int_delete()     | Remove an element from a Hash table
+ * | mutt_hash_int_find()       | Find the HashElem data in a Hash table element using a key
+ * | mutt_hash_int_insert()     | Add a new element to the Hash table (with integer keys)
+ * | mutt_hash_set_destructor() | Set the destructor for a Hash Table
+ * | mutt_hash_typed_insert()   | XXX
+ * | mutt_hash_walk()           | Iterate through all the HashElem's in a Hash table
  */
 
 #include "config.h"
@@ -161,12 +163,11 @@ static struct Hash *new_hash(int nelem)
 
 /**
  * union_hash_insert - Insert into a hash table using a union as a key
- * @param table     Hash table to update
- * @param key       Key to hash on
- * @param type      Data type
- * @param data      Data to associate with `key'
- * @retval -1 on error
- * @retval >=0 on success, index into the hash table
+ * @param table Hash table to update
+ * @param key   Key to hash on
+ * @param type  Data type
+ * @param data  Data to associate with key
+ * @retval ptr Newly inserted HashElem
  */
 static struct HashElem *union_hash_insert(struct Hash *table, union HashKey key,
                                           int type, void *data)
@@ -330,12 +331,26 @@ struct Hash *mutt_hash_int_create(int nelem, int flags)
   return table;
 }
 
-void mutt_hash_set_destructor(struct Hash *hash, hash_destructor fn, intptr_t fn_data)
+/**
+ * mutt_hash_set_destructor - Set the destructor for a Hash Table
+ * @param table   Hash table to use
+ * @param fn      Callback function to free Hash Table's resources
+ * @param fn_data Data to pass to the callback function
+ */
+void mutt_hash_set_destructor(struct Hash *table, hash_destructor fn, intptr_t fn_data)
 {
-  hash->destroy = fn;
-  hash->dest_data = fn_data;
+  table->destroy = fn;
+  table->dest_data = fn_data;
 }
 
+/**
+ * mutt_hash_typed_insert - Insert a string with type info into a Hash Table
+ * @param table  Hash table to use
+ * @param strkey String key
+ * @param type   Type to associate with the key
+ * @param data   Private data associated with the key
+ * @retval ptr Newly inserted HashElem
+ */
 struct HashElem *mutt_hash_typed_insert(struct Hash *table, const char *strkey,
                                         int type, void *data)
 {
@@ -349,8 +364,7 @@ struct HashElem *mutt_hash_typed_insert(struct Hash *table, const char *strkey,
  * @param table  Hash table (with string keys)
  * @param strkey String key
  * @param data   Private data associated with the key
- * @retval -1 on error
- * @retval >=0 on success, index into the hash table
+ * @retval ptr Newly inserted HashElem
  */
 struct HashElem *mutt_hash_insert(struct Hash *table, const char *strkey, void *data)
 {
@@ -362,8 +376,7 @@ struct HashElem *mutt_hash_insert(struct Hash *table, const char *strkey, void *
  * @param table  Hash table (with integer keys)
  * @param intkey Integer key
  * @param data   Private data associated with the key
- * @retval -1 on error
- * @retval >=0 on success, index into the hash table
+ * @retval ptr Newly inserted HashElem
  */
 struct HashElem *mutt_hash_int_insert(struct Hash *table, unsigned int intkey, void *data)
 {
@@ -460,7 +473,7 @@ void mutt_hash_int_delete(struct Hash *table, unsigned int intkey, const void *d
 
 /**
  * mutt_hash_destroy - Destroy a hash table
- * @param ptr     Pointer to the hash table to be freed
+ * @param ptr Hash Table to be freed
  */
 void mutt_hash_destroy(struct Hash **ptr)
 {
diff --git a/mutt/mbyte.c b/mutt/mbyte.c
index 9cde9f057..71daa854d 100644
--- a/mutt/mbyte.c
+++ b/mutt/mbyte.c
@@ -25,10 +25,6 @@
  *
  * Some commonly-used multi-byte string manipulation routines.
  *
- * | Data                    | Description
- * | :---------------------- | :--------------------------------------------------
- * | #ReplacementChar        | When a Unicode character can't be displayed, use this instead
- *
  * | Function                             | Description
  * | :----------------------------------- | :---------------------------------------------------------
  * | mutt_mb_charlen()                    | Count the bytes in a (multibyte) character
diff --git a/mutt/parameter.c b/mutt/parameter.c
index a8f79a59c..dcb7c3ccd 100644
--- a/mutt/parameter.c
+++ b/mutt/parameter.c
@@ -142,7 +142,7 @@ void mutt_param_set(struct ParameterList* p, const char *attribute, const char *
 
 /**
  * mutt_param_delete - Delete a matching Parameter
- * @param[in[  p         ParameterList
+ * @param[in]  p         ParameterList
  * @param[in]  attribute Attribute to match
  */
 void mutt_param_delete(struct ParameterList *p, const char *attribute)
diff --git a/mutt/regex.c b/mutt/regex.c
index 0ba3cc05f..2d77e3ab6 100644
--- a/mutt/regex.c
+++ b/mutt/regex.c
@@ -27,14 +27,14 @@
  *
  * | Function                  | Description
  * | :------------------------ | :------------------------------------------
+ * | mutt_regex_compile()      | Create an Regex from a string
+ * | mutt_regex_create()       | Create an Regex from a string
+ * | mutt_regex_free()         | Free a Regex object
  * | mutt_regexlist_add()      | Compile a regex string and add it to a list
  * | mutt_regexlist_free()     | Free a RegexList object
  * | mutt_regexlist_match()    | Does a string match any Regex in the list?
  * | mutt_regexlist_new()      | Create a new RegexList
  * | mutt_regexlist_remove()   | Remove a Regex from a list
- * | mutt_regex_compile()      | Create an Regex from a string
- * | mutt_regex_create()       | Create an Regex from a string
- * | mutt_regex_free()         | Free a Regex object
  * | mutt_replacelist_add()    | Add a pattern and a template to a list
  * | mutt_replacelist_apply()  | Apply replacements to a buffer
  * | mutt_replacelist_free()   | Free a ReplaceList object
diff --git a/mutt/rfc2047.c b/mutt/rfc2047.c
index 3f91f2a54..af915f37c 100644
--- a/mutt/rfc2047.c
+++ b/mutt/rfc2047.c
@@ -27,10 +27,10 @@
  *
  * RFC2047 MIME extensions encoding / decoding routines.
  *
- * | Function                      | Description
- * | :---------------------------- | :-----------------------------------------
- * | mutt_rfc2047_decode()         | Decode any RFC2047-encoded header fields
- * | mutt_rfc2047_encode()         | RFC-2047-encode a string
+ * | Function              | Description
+ * | :-------------------- | :-----------------------------------------
+ * | mutt_rfc2047_decode() | Decode any RFC2047-encoded header fields
+ * | mutt_rfc2047_encode() | RFC-2047-encode a string
  */
 
 #include "config.h"
diff --git a/mutt/string.c b/mutt/string.c
index 9870d4a11..7038c0f52 100644
--- a/mutt/string.c
+++ b/mutt/string.c
@@ -42,6 +42,7 @@
  * | mutt_str_lws_len()            | Measure the linear-white-space at the beginning of a string
  * | mutt_str_lws_rlen()           | Measure the linear-white-space at the end of a string
  * | mutt_str_next_word()          | Find the next word in a string
+ * | mutt_str_pretty_size()        | Display an abbreviated size, e.g. 3.4K
  * | mutt_str_remove_trailing_ws() | Trim trailing whitespace from a string
  * | mutt_str_replace()            | Replace one string with another
  * | mutt_str_rstrnstr()           | Find last instance of a substring