doxy: add comment blocks

diff --git a/icommands.c b/icommands.c
index 3f688942bc68cbc4cd47bf326d63c5d414238fc6..73acabcb13c1350cc4655416c63428533ffbf751 100644 (file)
--- a/icommands.c
+++ b/icommands.c
@@ -142,7 +142,7 @@ static enum CommandResult icmd_set(struct Buffer *buf, struct Buffer *s,
 }
 
 /**
- * icmd_set - Parse 'version' command - Implements ::icommand_t
+ * icmd_version - Parse 'version' command - Implements ::icommand_t
  */
 static enum CommandResult icmd_version(struct Buffer *buf, struct Buffer *s,
                                        unsigned long data, struct Buffer *err)

diff --git a/imap/imap.c b/imap/imap.c
index e9bbec8cd0ad2ba3a5982600b857bffb561bb319..5748b9bfe82704f5c07d5220e8f29743e6c21133 100644 (file)
--- a/imap/imap.c
+++ b/imap/imap.c
@@ -980,6 +980,14 @@ bool imap_has_flag(struct ListHead *flag_list, const char *flag)
   return false;
 }
 
+/**
+ * compare_uid - Compare two UIDs
+ * @param a First UID
+ * @param b Second UID
+ * @retval -1 a precedes b
+ * @retval  0 a and b are identical
+ * @retval  1 b precedes a
+ */
 static int compare_uid(const void *a, const void *b)
 {
   struct Email **ea = (struct Email **) a;

diff --git a/imap/util.c b/imap/util.c
index bd6c9a5216b87baf7f111b2109672f16f34a5f88..6550645ef6388406fd5eeaa1d76bac91c30b805c 100644 (file)
--- a/imap/util.c
+++ b/imap/util.c
@@ -114,6 +114,8 @@ struct ImapAccountData *imap_adata_new(void)
 
 /**
  * imap_adata_get - Get the Account data for this mailbox
+ * @param m Mailbox
+ * @retval ptr Private data
  */
 struct ImapAccountData *imap_adata_get(struct Mailbox *m)
 {
@@ -124,6 +126,11 @@ struct ImapAccountData *imap_adata_get(struct Mailbox *m)
 
 /**
  * imap_adata_find - Find the Account data for this path
+ * @param path  Path to search for
+ * @param adata Imap Account data
+ * @param mdata Imap Mailbox data
+ * @retval  0 Success
+ * @retval -1 Failure
  */
 int imap_adata_find(const char *path, struct ImapAccountData **adata,
                     struct ImapMboxData **mdata)

diff --git a/mutt/path.c b/mutt/path.c
index e0d7e2c26ef9be65d46a9a85e9592c18b220bfc9..6b3ff0d4d1660a72c326228d87a07b206c71ce7d 100644 (file)
--- a/mutt/path.c
+++ b/mutt/path.c
@@ -528,7 +528,7 @@ bool mutt_path_abbr_folder(char *buf, size_t buflen, const char *folder)
 }
 
 /**
- * mutt_escape_path - Escapes single quotes in a path for a command string
+ * mutt_path_escape - Escapes single quotes in a path for a command string
  * @param src the path to escape
  * @retval ptr The escaped string
  */

diff --git a/mutt/string.c b/mutt/string.c
index d3d9618d0d2df934edb492eacb6ef76ecf1fd8b7..6034cfdb64744abfbac62b4accba0c121b3ed073 100644 (file)
--- a/mutt/string.c
+++ b/mutt/string.c
@@ -145,8 +145,7 @@ static inline bool char_cmp_lower(char a, char b)
 typedef bool (*char_cmp)(char, char);
 
 /**
- * get_char_cmp - Retrieve the correct function to compare characters according
- * to a case sensitivity setting.
+ * get_char_cmp - Retrieve the correct function to compare characters according to a case sensitivity setting.
  * @param cs Case sensitivity setting
  * @retval A char_cmp function pointer
  */

diff --git a/mx.c b/mx.c
index 514b3821b14314461d8e6a30b66198520e5af4f7..ebf39ff14cd836d6c71c820c4460401e16f758a5 100644 (file)
--- a/mx.c
+++ b/mx.c
@@ -1568,7 +1568,7 @@ int mx_mbox_check_stats(struct Mailbox *m, int flags)
 }
 
 /**
- * mx_save_to_header_cache - Save message to the header cache - Wrapper for MxOps::msg_save_hcache()
+ * mx_save_hcache - Save message to the header cache - Wrapper for MxOps::msg_save_hcache()
  * @param m Mailbox
  * @param e Email
  * @retval  0 Success

diff --git a/ncrypt/crypt.c b/ncrypt/crypt.c
index 1738d3d8f6ed289d259bc6902374517c92a437a7..6c27d7da23657b090f1e0e3a9fa48053084b207e 100644 (file)
--- a/ncrypt/crypt.c
+++ b/ncrypt/crypt.c
@@ -1038,6 +1038,11 @@ static void crypt_fetch_signatures(struct Body ***signatures, struct Body *a, in
   }
 }
 
+/**
+ * mutt_should_hide_protected_subject - Should NeoMutt hide the protected subject?
+ * @param e Email to test
+ * @retval bool True if the subject should be protected
+ */
 bool mutt_should_hide_protected_subject(struct Email *e)
 {
   if (CryptProtectedHeadersWrite && (e->security & ENCRYPT) && !(e->security & INLINE) &&

diff --git a/ncrypt/crypt_gpgme.c b/ncrypt/crypt_gpgme.c
index 578d4f95453fe2116141a40c01343f809c79703e..5132e3cbc79f09385bf4bf54d95946e4fc877f2e 100644 (file)
--- a/ncrypt/crypt_gpgme.c
+++ b/ncrypt/crypt_gpgme.c
@@ -205,25 +205,43 @@ static void print_utf8(FILE *fp, const char *buf, size_t len)
   FREE(&tstr);
 }
 
-/* Compare function for version strings.  The return value is
- * like strcmp().  LEVEL may be
- *   0 - reserved
- *   1 - format is "<major><patchlevel>".
- *   2 - format is "<major>.<minor><patchlevel>".
- *   3 - format is "<major>.<minor>.<micro><patchlevel>".
- * To ignore the patchlevel in the comparison add 10 to LEVEL.  To get
- * a reverse sorting order use a negative number.   */
 #if GPGRT_VERSION_NUMBER >= 0x012100 /* libgpg-error >= 1.33 */
+/**
+ * cmp_version_strings - Compare version strings
+ * @param a First version string
+ * @param b Second version string
+ * @param level Level to compare (see below)
+ * @retval -1 a precedes b
+ * @retval  0 a and b are identical
+ * @retval  1 b precedes a
+ *
+ * `level` may be
+ * - 0 reserved
+ * - 1 format is "<major><patchlevel>"
+ * - 2 format is "<major>.<minor><patchlevel>"
+ * - 3 format is "<major>.<minor>.<micro><patchlevel>"
+ *
+ * To ignore the patchlevel in the comparison add 10 to LEVEL.
+ * To get a reverse sorting order use a negative number.
+ */
 static int cmp_version_strings(const char *a, const char *b, int level)
 {
   return gpgrt_cmp_version(a, b, level);
 }
 #elif GPGME_VERSION_NUMBER >= 0x010900 /* gpgme >= 1.9.0 */
 
-/* This function parses the first portion of the version number S and
+/**
+ * parse_version_number - Parse a version string
+ * @param[in]  s String to parse
+ * @param[out] number
+ * @retval ptr  Remainder of the string
+ * @retval NULL Error
+ *
+ * This function parses the first portion of the version number S and
  * stores it at NUMBER.  On success, this function returns a pointer
  * into S starting with the first character, which is not part of the
- * initial number portion; on failure, NULL is returned.  */
+ * initial number portion; on failure, NULL is returned.
+ */
 static const char *parse_version_number(const char *s, int *number)
 {
   int val = 0;
@@ -239,15 +257,24 @@ static const char *parse_version_number(const char *s, int *number)
   return val < 0 ? NULL : s;
 }
 
-/* This function breaks up the complete string-representation of the
- * version number S, which is of the following structure: <major
- * number>.<minor number>.<micro number><patch level>.  The major,
- * minor and micro number components will be stored in *MAJOR, *MINOR
- * and *MICRO.  If MINOR or MICRO is NULL the version number is
- * assumed to have just 1 respective 2 parts.
+/**
+ * parse_version_string - Parse a version string
+ * @param s String to parse
+ * @param major Version MAJOR.x.x
+ * @param minor Version x.MINOR.x
+ * @param micro Version x.x.MICRO
+ * @retval str  Patch level
+ * @retval NULL If there are fewer parts
+ *
+ * Break up the complete string-representation of the version number S, which
+ * is of the following struture: <major number>.<minor number>.<micro
+ * number><patch level>.  The major, minor and micro number components will be
+ * stored in *MAJOR, *MINOR and *MICRO.  If MINOR or MICRO is NULL the version
+ * number is assumed to have just 1 or 2 parts respectively.
  *
  * On success, the last component, the patch level, will be returned;
- * in failure, NULL will be returned.  */
+ * in failure, NULL will be returned.
+ */
 static const char *parse_version_string(const char *s, int *major, int *minor, int *micro)
 {
   s = parse_version_number(s, major);
@@ -284,8 +311,15 @@ static const char *parse_version_string(const char *s, int *major, int *minor, i
   return s; /* patchlevel */
 }
 
-/* Substitute for the gpgrt based implementation.
- * See above for a description.   */
+/**
+ * cmp_version_strings - Compare two version strings
+ * @param a First version string
+ * @param b Second version string
+ * @param level Level to compare
+ *
+ * Substitute for the gpgrt based implementation.
+ * See above for a description.
+ */
 static int cmp_version_strings(const char *a, const char *b, int level)
 {
   int a_major, a_minor, a_micro;
@@ -724,7 +758,13 @@ static gpgme_data_t create_gpgme_data(void)
 }
 
 #if GPGME_VERSION_NUMBER >= 0x010900 /* gpgme >= 1.9.0 */
-/* Return true if the OpenPGP engine's version is at least VERSION. */
+/**
+ * have_gpg_version - Do we have a sufficent GPG version
+ * @param version Minimum version
+ * @retval bool ZZZ
+ *
+ * Return true if the OpenPGP engine's version is at least VERSION.
+ */
 static int have_gpg_version(const char *version)
 {
   static char *engine_version;

diff --git a/state.c b/state.c
index 51d4fdf20f1642dd56db6968914c61b264dcc820..2d5eb4038cd5210a1a72118926e27728c4a36a7c 100644 (file)
--- a/state.c
+++ b/state.c
@@ -47,7 +47,7 @@ void state_mark_attach(struct State *s)
 }
 
 /**
- * state_mark_attach - Write a unique marker around protected headers
+ * state_mark_protected_header - Write a unique marker around protected headers
  * @param s State to write to
  */
 void state_mark_protected_header(struct State *s)