mx api: document all implementation functions

compress.c

@@ -445,10 +445,7 @@ static int execute_command(struct Context *ctx, const char *command, const char
 }
 
 /**
- * comp_mbox_open - Open a compressed mailbox
- * @param ctx Mailbox to open
- * @retval  0 Success
- * @retval -1 Error
+ * comp_mbox_open - Implements MxOps::mbox_open()
  *
  * Set up a compressed mailbox to be read.
  * Decompress the mailbox and set up the paths and hooks needed.
@@ -508,11 +505,9 @@ static int comp_mbox_open(struct Context *ctx)
 }
 
 /**
- * comp_mbox_open_append - Open a compressed mailbox for appending
- * @param ctx   Mailbox to open
- * @param flags e.g. Does the file already exist?
- * @retval  0 Success
- * @retval -1 Failure
+ * comp_mbox_open_append - Implements MxOps::mbox_open_append()
+ *
+ * flags may also contain #MUTT_NEWFOLDER
  *
  * To append to a compressed mailbox we need an append-hook (or both open- and
  * close-hooks).
@@ -589,10 +584,7 @@ static int comp_mbox_open_append(struct Context *ctx, int flags)
 }
 
 /**
- * comp_mbox_close - Close a compressed mailbox
- * @param ctx Mailbox to close
- * @retval  0 Success
- * @retval -1 Failure
+ * comp_mbox_close - Implements MxOps::mbox_close()
  *
  * If the mailbox has been changed then re-compress the tmp file.
  * Then delete the tmp file.
@@ -663,7 +655,7 @@ static int comp_mbox_close(struct Context *ctx)
 }
 
 /**
- * comp_mbox_check - Check for changes in the compressed file
+ * comp_mbox_check - Implements MxOps::mbox_check()
  * @param ctx        Mailbox
  * @param index_hint Currently selected mailbox
  * @retval 0              Mailbox OK
@@ -710,12 +702,7 @@ static int comp_mbox_check(struct Context *ctx, int *index_hint)
 }
 
 /**
- * comp_msg_open - Delegated to mbox handler
- * @param ctx   Mailbox
- * @param msg   Message to open
- * @param msgno Message number
- * @retval  0 Success
- * @retval -1 Failure
+ * comp_msg_open - Implements MxOps::msg_open()
  */
 static int comp_msg_open(struct Context *ctx, struct Message *msg, int msgno)
 {
@@ -735,11 +722,7 @@ static int comp_msg_open(struct Context *ctx, struct Message *msg, int msgno)
 }
 
 /**
- * comp_msg_close - Delegated to mbox handler
- * @param ctx Mailbox
- * @param msg Message to close
- * @retval  0 Success
- * @retval -1 Failure
+ * comp_msg_close - Implements MxOps::msg_close()
  */
 static int comp_msg_close(struct Context *ctx, struct Message *msg)
 {
@@ -759,11 +742,7 @@ static int comp_msg_close(struct Context *ctx, struct Message *msg)
 }
 
 /**
- * comp_msg_commit - Delegated to mbox handler
- * @param ctx Mailbox
- * @param msg Message to commit
- * @retval  0 Success
- * @retval -1 Failure
+ * comp_msg_commit - Implements MxOps::msg_commit()
  */
 static int comp_msg_commit(struct Context *ctx, struct Message *msg)
 {
@@ -783,12 +762,7 @@ static int comp_msg_commit(struct Context *ctx, struct Message *msg)
 }
 
 /**
- * comp_msg_open_new - Delegated to mbox handler
- * @param ctx Mailbox
- * @param msg Message to commit
- * @param hdr Email header
- * @retval  0 Success
- * @retval -1 Failure
+ * comp_msg_open_new - Implements MxOps::msg_open_new()
  */
 static int comp_msg_open_new(struct Context *ctx, struct Message *msg, struct Header *hdr)
 {
@@ -859,14 +833,10 @@ bool mutt_comp_can_read(const char *path)
 }
 
 /**
- * comp_mbox_sync - Save changes to the compressed mailbox file
- * @param ctx        Mailbox to sync
- * @param index_hint Currently selected mailbox
- * @retval  0 Success
- * @retval -1 Failure
+ * comp_mbox_sync - Implements MxOps::mbox_sync()
  *
- * Changes in NeoMutt only affect the tmp file.  Calling comp_mbox_sync()
- * will commit them to the compressed file.
+ * Changes in NeoMutt only affect the tmp file.
+ * Calling comp_mbox_sync() will commit them to the compressed file.
  */
 static int comp_mbox_sync(struct Context *ctx, int *index_hint)
 {
@@ -935,7 +905,7 @@ int mutt_comp_valid_command(const char *cmd)
 
 // clang-format off
 /**
- * mx_comp_ops - Mailbox callback functions
+ * struct mx_comp_ops - Mailbox callback functions for compressed mailboxes
  *
  * Compress only uses open, close and check.
  * The message functions are delegated to mbox.

doxygen/doxygen.conf

@@ -868,7 +868,7 @@ IMAGE_PATH             =
 # need to set EXTENSION_MAPPING for the extension otherwise the files are not
 # properly processed by doxygen.
 
-INPUT_FILTER = "sed -e 's/^ \* \(struct\|enum\|union\) [^ ]\+ - / * /' -e 's/^ \* [a-zA-Z0-9_]\+ - / * /' -e 's/^ \* Copyright ([Cc]) [-0-9,]\+ \([^<]*\)\( <.*>\)*/ * - \1/'"
+INPUT_FILTER = "sed -e 's/^ \+\* \(struct\|enum\|union\) [^ ]\+ - / * /' -e 's/^ \+\* [a-zA-Z0-9_]\+ - / * /' -e 's/^ \* Copyright ([Cc]) [-0-9,]\+ \([^<]*\)\( <.*>\)*/ * - \1/'"
 
 # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
 # basis. Doxygen will compare the file name with each pattern and apply the

imap/imap.c

@@ -1969,10 +1969,7 @@ int imap_fast_trash(struct Context *ctx, char *dest)
 }
 
 /**
- * imap_mbox_open - Open an IMAP mailbox
- * @param ctx Context
- * @retval  0 Success
- * @retval -1 Failure
+ * imap_mbox_open - Implements MxOps::mbox_open()
  */
 static int imap_mbox_open(struct Context *ctx)
 {
@@ -2195,11 +2192,7 @@ static int imap_mbox_open(struct Context *ctx)
 }
 
 /**
- * imap_mbox_open_append - Open an IMAP mailbox to append
- * @param ctx   Context
- * @param flags Mailbox flags (UNUSED)
- * @retval  0 Success
- * @retval -1 Failure
+ * imap_mbox_open_append - Implements MxOps::mbox_open_append()
  */
 static int imap_mbox_open_append(struct Context *ctx, int flags)
 {
@@ -2247,8 +2240,7 @@ static int imap_mbox_open_append(struct Context *ctx, int flags)
 }
 
 /**
- * imap_mbox_close - Clean up IMAP data in Context
- * @param ctx Context
+ * imap_mbox_close - Implements MxOps::mbox_close()
  * @retval 0 Always
  */
 static int imap_mbox_close(struct Context *ctx)
@@ -2311,12 +2303,7 @@ static int imap_mbox_close(struct Context *ctx)
 }
 
 /**
- * imap_msg_open_new - Open an IMAP message
- * @param ctx  Context (UNUSED)
- * @param msg  Message to open
- * @param hdr  Header (UNUSED)
- * @retval  0 Success
- * @retval -1 Failure
+ * imap_msg_open_new - Implements MxOps::msg_open_new()
  */
 static int imap_msg_open_new(struct Context *ctx, struct Message *msg, struct Header *hdr)
 {
@@ -2334,7 +2321,7 @@ static int imap_msg_open_new(struct Context *ctx, struct Message *msg, struct He
 }
 
 /**
- * imap_mbox_check - Check for new mail (reopen mailbox if necessary)
+ * imap_mbox_check - Implements MxOps::mbox_check()
  * @param ctx        Context
  * @param index_hint Remember our place in the index
  * @retval >0 Success, e.g. #MUTT_REOPENED
@@ -2556,14 +2543,7 @@ int imap_sync_mailbox(struct Context *ctx, int expunge)
 }
 
 /**
- * imap_tags_edit - Prompt and validate new messages tags
- * @param ctx    Context
- * @param tags   Existing tags
- * @param buf    Buffer to store the tags
- * @param buflen Length of buffer
- * @retval -1 Error
- * @retval  0 No valid user input
- * @retval  1 Buf set
+ * imap_tags_edit - Implements MxOps::tags_edit()
  */
 static int imap_tags_edit(struct Context *ctx, const char *tags, char *buf, size_t buflen)
 {
@@ -2639,12 +2619,7 @@ static int imap_tags_edit(struct Context *ctx, const char *tags, char *buf, size
 }
 
 /**
- * imap_tags_commit - Add/Change/Remove flags from headers
- * @param ctx Context
- * @param hdr Header
- * @param buf List of tags
- * @retval  0 Success
- * @retval -1 Error
+ * imap_tags_commit - Implements MxOps::tags_commit()
  *
  * This method update the server flags on the server by
  * removing the last know custom flags of a header
@@ -2735,7 +2710,7 @@ static int imap_tags_commit(struct Context *ctx, struct Header *hdr, char *buf)
 
 // clang-format off
 /**
- * mx_imap_ops - Mailbox callback functions
+ * struct mx_imap_ops - Mailbox callback functions for IMAP mailboxes
  */
 struct MxOps mx_imap_ops = {
   .mbox_open        = imap_mbox_open,

imap/message.c

@@ -971,12 +971,7 @@ int imap_read_headers(struct ImapData *idata, unsigned int msn_begin, unsigned i
 }
 
 /**
- * imap_msg_open - Fetch an email from an IMAP server
- * @param ctx   Context
- * @param msg   Message to fetch
- * @param msgno Index into ctr->hdrs
- * @retval  0 Success
- * @retval -1 Failure
+ * imap_msg_open - Implements MxOps::msg_open()
  */
 int imap_msg_open(struct Context *ctx, struct Message *msg, int msgno)
 {
@@ -1203,29 +1198,23 @@ int imap_msg_open(struct Context *ctx, struct Message *msg, int msgno)
 
 /**
  * imap_msg_close - Close an email
- * @param ctx Context
- * @param msg Email info
- * @retval 0   Success
- * @retval EOF Failure, see errno
+ *
+ * @note May also return EOF Failure, see errno
  */
 int imap_msg_close(struct Context *ctx, struct Message *msg)
 {
   return mutt_file_fclose(&msg->fp);
 }
 
 /**
- * imap_msg_commit - Save changes to an email
- * @param ctx Context
- * @param msg Email info
- * @retval 0   Success
- * @retval EOF fclose() failed, see errno
- * @retval -1  Failure
+ * imap_msg_commit - Implements MxOps::msg_commit()
+ *
+ * @note May also return EOF Failure, see errno
  */
 int imap_msg_commit(struct Context *ctx, struct Message *msg)
 {
   int r = mutt_file_fclose(&msg->fp);
-
-  if (r)
+  if (r != 0)
     return r;
 
   return imap_append_message(ctx, msg);