mx api: document all implementation functions
authorRichard Russon <rich@flatcap.org>
Wed, 6 Jun 2018 01:05:11 +0000 (02:05 +0100)
committerRichard Russon <rich@flatcap.org>
Wed, 6 Jun 2018 12:30:48 +0000 (13:30 +0100)
compress.c
doxygen/doxygen.conf
imap/imap.c
imap/message.c
mbox.c
mh.c
mutt_notmuch.c
mx.h
nntp.c
pop.c

index 0e0f583467b403193e71e6f2bf74dc071e40b2d6..c6a7484bc73a8dcbbecd2f783f554d0ad5f25dbc 100644 (file)
@@ -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 @@ or_fail:
 }
 
 /**
- * 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 @@ oa_fail1:
 }
 
 /**
- * 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.
index 37cb439ce86abe5ea3e6d4494dc2272e1ac97c4d..6cef7235b885e4f4f84fb0c87d448785330a0219 100644 (file)
@@ -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
index 763620f10f194def41bbb459e70c7b464338130a..d851551634cf4482aaf8398184284cba7c6d5ea4 100644 (file)
@@ -1969,10 +1969,7 @@ out:
 }
 
 /**
- * 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 @@ fail_noidata:
 }
 
 /**
- * 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 @@ out:
 }
 
 /**
- * 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,
index 9411cd2af6798c70a2f14097d2376979868482d8..72d813828ff6058a12b0f8f5f3be793381c42dd4 100644 (file)
@@ -971,12 +971,7 @@ error_out_0:
 }
 
 /**
- * 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,10 +1198,8 @@ bail:
 
 /**
  * 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)
 {
@@ -1214,18 +1207,14 @@ int imap_msg_close(struct Context *ctx, struct Message *msg)
 }
 
 /**
- * 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);
diff --git a/mbox.c b/mbox.c
index 8a3163efdd5a6b727610ae747f8872716121ce09..19044bc435e5d5caee96477a08f24184bece1fb0 100644 (file)
--- a/mbox.c
+++ b/mbox.c
@@ -439,7 +439,7 @@ static int mbox_parse_mailbox(struct Context *ctx)
 }
 
 /**
- * mbox_mbox_open - open a mbox or mmdf style mailbox
+ * mbox_mbox_open - Implements MxOps::mbox_open()
  */
 static int mbox_mbox_open(struct Context *ctx)
 {
@@ -471,6 +471,9 @@ static int mbox_mbox_open(struct Context *ctx)
   return rc;
 }
 
+/**
+ * mbox_mbox_open_append - Implements MxOps::mbox_open_append()
+ */
 static int mbox_mbox_open_append(struct Context *ctx, int flags)
 {
   ctx->fp = mutt_file_fopen(ctx->path, (flags & MUTT_NEWFOLDER) ? "w" : "a");
@@ -492,6 +495,10 @@ static int mbox_mbox_open_append(struct Context *ctx, int flags)
   return 0;
 }
 
+/**
+ * mbox_mbox_close - Implements MxOps::mbox_close()
+ * @retval 0 Always
+ */
 static int mbox_mbox_close(struct Context *ctx)
 {
   if (!ctx->fp)
@@ -510,6 +517,9 @@ static int mbox_mbox_close(struct Context *ctx)
   return 0;
 }
 
+/**
+ * mbox_msg_open - Implements MxOps::msg_open()
+ */
 static int mbox_msg_open(struct Context *ctx, struct Message *msg, int msgno)
 {
   msg->fp = ctx->fp;
@@ -517,6 +527,10 @@ static int mbox_msg_open(struct Context *ctx, struct Message *msg, int msgno)
   return 0;
 }
 
+/**
+ * mbox_msg_close - Implements MxOps::msg_close()
+ * @retval 0 Always
+ */
 static int mbox_msg_close(struct Context *ctx, struct Message *msg)
 {
   msg->fp = NULL;
@@ -524,6 +538,9 @@ static int mbox_msg_close(struct Context *ctx, struct Message *msg)
   return 0;
 }
 
+/**
+ * mbox_msg_commit - Implements MxOps::msg_commit()
+ */
 static int mbox_msg_commit(struct Context *ctx, struct Message *msg)
 {
   if (fputc('\n', msg->fp) == EOF)
@@ -538,6 +555,9 @@ static int mbox_msg_commit(struct Context *ctx, struct Message *msg)
   return 0;
 }
 
+/**
+ * mmdf_msg_commit - Implements MxOps::msg_commit()
+ */
 static int mmdf_msg_commit(struct Context *ctx, struct Message *msg)
 {
   if (fputs(MMDF_SEP, msg->fp) == EOF)
@@ -552,6 +572,10 @@ static int mmdf_msg_commit(struct Context *ctx, struct Message *msg)
   return 0;
 }
 
+/**
+ * mbox_msg_open_new - Implements MxOps::msg_open_new()
+ * @retval 0 Always
+ */
 static int mbox_msg_open_new(struct Context *ctx, struct Message *msg, struct Header *hdr)
 {
   msg->fp = ctx->fp;
@@ -774,7 +798,7 @@ static int reopen_mailbox(struct Context *ctx, int *index_hint)
 }
 
 /**
- * mbox_mbox_check - Has mailbox changed on disk
+ * mbox_mbox_check - Implements MxOps::mbox_check()
  * @param[in]  ctx        Context
  * @param[out] index_hint Keep track of current index selection
  * @retval #MUTT_REOPENED  Mailbox has been reopened
@@ -936,9 +960,7 @@ void mbox_reset_atime(struct Context *ctx, struct stat *st)
 }
 
 /**
- * mbox_mbox_sync - Sync a mailbox to disk
- * @retval  0 Success
- * @retval -1 Failure
+ * mbox_mbox_sync - Implements MxOps::mbox_sync()
  */
 static int mbox_mbox_sync(struct Context *ctx, int *index_hint)
 {
@@ -1306,6 +1328,9 @@ bail: /* Come here in case of disaster */
 }
 
 // clang-format off
+/**
+ * struct mx_mbox_ops - Mailbox callback functions for mbox mailboxes
+ */
 struct MxOps mx_mbox_ops = {
   .mbox_open        = mbox_mbox_open,
   .mbox_open_append = mbox_mbox_open_append,
@@ -1320,6 +1345,9 @@ struct MxOps mx_mbox_ops = {
   .tags_commit      = NULL,
 };
 
+/**
+ * struct mx_mmdf_ops - Mailbox callback functions for MMDF mailboxes
+ */
 struct MxOps mx_mmdf_ops = {
   .mbox_open        = mbox_mbox_open,
   .mbox_open_append = mbox_mbox_open_append,
diff --git a/mh.c b/mh.c
index 4c5e527219159fe64235a1ec56b3d58f8376b00b..3e16c15215417c9bed123979ae93d1b6f3d11403 100644 (file)
--- a/mh.c
+++ b/mh.c
@@ -1231,6 +1231,10 @@ static void maildir_delayed_parsing(struct Context *ctx, struct Maildir **md,
   mh_sort_natural(ctx, md);
 }
 
+/**
+ * mh_mbox_close - Implements MxOps::mbox_close()
+ * @retval 0 Always
+ */
 static int mh_mbox_close(struct Context *ctx)
 {
   FREE(&ctx->data);
@@ -1322,6 +1326,9 @@ static int maildir_mbox_open(struct Context *ctx)
   return maildir_read_dir(ctx);
 }
 
+/**
+ * maildir_mbox_open_append - Implements MxOps::mbox_open_append()
+ */
 static int maildir_mbox_open_append(struct Context *ctx, int flags)
 {
   if (!(flags & MUTT_APPENDNEW))
@@ -1369,11 +1376,17 @@ static int maildir_mbox_open_append(struct Context *ctx, int flags)
   return 0;
 }
 
+/**
+ * mh_mbox_open - Implements MxOps::mbox_open()
+ */
 static int mh_mbox_open(struct Context *ctx)
 {
   return mh_read_dir(ctx, NULL);
 }
 
+/**
+ * mh_mbox_open_append - Implements MxOps::mbox_open_append()
+ */
 static int mh_mbox_open_append(struct Context *ctx, int flags)
 {
   if (!(flags & MUTT_APPENDNEW))
@@ -1401,10 +1414,11 @@ static int mh_mbox_open_append(struct Context *ctx, int flags)
   return 0;
 }
 
-/*
+/**
+ * mh_msg_open_new - Implements MxOps::msg_open_new()
+ *
  * Open a new (temporary) message in an MH folder.
  */
-
 static int mh_msg_open_new(struct Context *ctx, struct Message *msg, struct Header *hdr)
 {
   return mh_mkstemp(ctx, &msg->fp, &msg->path);
@@ -1462,27 +1476,38 @@ static int maildir_mh_open_message(struct Context *ctx, struct Message *msg,
   return 0;
 }
 
+/**
+ * maildir_msg_open - Implements MxOps::msg_open()
+ */
 static int maildir_msg_open(struct Context *ctx, struct Message *msg, int msgno)
 {
   return maildir_mh_open_message(ctx, msg, msgno, 1);
 }
 
+/**
+ * mh_msg_open - Implements MxOps::msg_open()
+ */
 static int mh_msg_open(struct Context *ctx, struct Message *msg, int msgno)
 {
   return maildir_mh_open_message(ctx, msg, msgno, 0);
 }
 
+/**
+ * nm_msg_close - Close a message
+ *
+ * @note May also return EOF Failure, see errno
+ */
 static int mh_msg_close(struct Context *ctx, struct Message *msg)
 {
   return mutt_file_fclose(&msg->fp);
 }
 
 /**
- * maildir_msg_open_new - Open a new message in a maildir folder
+ * maildir_msg_open_new - Implements MxOps::msg_open_new()
  *
  * Open a new (temporary) message in a maildir folder.
  *
- * Note that this uses _almost_ the maildir file name format,
+ * @note This uses _almost_ the maildir file name format,
  * but with a {cur,new} prefix.
  */
 static int maildir_msg_open_new(struct Context *ctx, struct Message *msg,
@@ -1646,15 +1671,18 @@ static int md_commit_message(struct Context *ctx, struct Message *msg, struct He
   }
 }
 
+/**
+ * maildir_msg_commit - Implements MxOps::msg_commit()
+ */
 static int maildir_msg_commit(struct Context *ctx, struct Message *msg)
 {
   return md_commit_message(ctx, msg, NULL);
 }
 
-/*
+/**
+ * mh_commit_msg - XXX
  * commit a message to an MH folder.
  */
-
 static int mh_commit_msg(struct Context *ctx, struct Message *msg,
                          struct Header *hdr, short updseq)
 {
@@ -1732,6 +1760,9 @@ static int mh_commit_msg(struct Context *ctx, struct Message *msg,
   return 0;
 }
 
+/**
+ * mh_msg_commit - Implements MxOps::msg_commit()
+ */
 static int mh_msg_commit(struct Context *ctx, struct Message *msg)
 {
   return mh_commit_msg(ctx, msg, NULL, 1);
@@ -2012,7 +2043,7 @@ static void maildir_update_tables(struct Context *ctx, int *index_hint)
 }
 
 /**
- * maildir_mbox_check - Check for new mail
+ * maildir_mbox_check - Implements mbox_check()
  *
  * This function handles arrival of new mail and reopening of maildir folders.
  * The basic idea here is we check to see if either the new or cur
@@ -2171,7 +2202,7 @@ static int maildir_mbox_check(struct Context *ctx, int *index_hint)
 }
 
 /**
- * mh_mbox_check - Check for new mail
+ * mh_mbox_check - Implements MxOps::mbox_check()
  *
  * This function handles arrival of new mail and reopening of mh/maildir
  * folders. Things are getting rather complex because we don't have a
@@ -2291,6 +2322,9 @@ static int mh_mbox_check(struct Context *ctx, int *index_hint)
   return 0;
 }
 
+/**
+ * mh_mbox_sync - Implements MxOps::mbox_sync()
+ */
 static int mh_mbox_sync(struct Context *ctx, int *index_hint)
 {
   int i, j;
@@ -2607,6 +2641,9 @@ bool mx_is_mh(const char *path)
 }
 
 // clang-format off
+/**
+ * struct mx_maildir_ops - Mailbox callback functions for Maildir mailboxes
+ */
 struct MxOps mx_maildir_ops = {
   .mbox_open        = maildir_mbox_open,
   .mbox_open_append = maildir_mbox_open_append,
@@ -2621,6 +2658,9 @@ struct MxOps mx_maildir_ops = {
   .tags_commit      = NULL,
 };
 
+/**
+ * struct mx_mh_ops - Mailbox callback functions for MH mailboxes
+ */
 struct MxOps mx_mh_ops = {
   .mbox_open        = mh_mbox_open,
   .mbox_open_append = mh_mbox_open_append,
index 6598a3ae77bb0fb5dce07255c2a636ae3af0410f..21e13d9cd1d37b20e0818a61515fd351df9c34cc 100644 (file)
@@ -2005,14 +2005,7 @@ void nm_query_window_backward(void)
 }
 
 /**
- * nm_tags_edit - Prompt new messages tags
- * @param ctx    Mailbox
- * @param tags   Existing tags (UNUSED)
- * @param buf    Buffer for message tags
- * @param buflen Length of buffer
- * @retval -1 Error
- * @retval 0  No valid user input
- * @retval 1  Buffer set
+ * nm_tags_edit - Implements MxOps::tags_edit()
  */
 static int nm_tags_edit(struct Context *ctx, const char *tags, char *buf, size_t buflen)
 {
@@ -2023,12 +2016,7 @@ static int nm_tags_edit(struct Context *ctx, const char *tags, char *buf, size_t
 }
 
 /**
- * nm_tags_commit - Save the tags to a message
- * @param ctx Mailbox
- * @param hdr Email Header
- * @param buf Buffer containing tags
- * @retval  0 Success
- * @retval -1 Failure
+ * nm_tags_commit - Implements MxOps::tags_commit()
  */
 static int nm_tags_commit(struct Context *ctx, struct Header *hdr, char *buf)
 {
@@ -2410,12 +2398,8 @@ done:
 }
 
 /**
- * nm_mbox_open - Open a notmuch virtual mailbox
- * @param ctx Mailbox
- * @retval  0 Success
- * @retval -1 Error
+ * nm_mbox_open - Implements MxOps::mbox_open()
  */
-
 static int nm_mbox_open(struct Context *ctx)
 {
   notmuch_query_t *q = NULL;
@@ -2464,10 +2448,7 @@ static int nm_mbox_open(struct Context *ctx)
 }
 
 /**
- * nm_mbox_close - Close a notmuch virtual mailbox
- * @param ctx Mailbox
- * @retval  0 Success
- * @retval -1 Error
+ * nm_mbox_close - Implements MxOps::mbox_close()
  */
 static int nm_mbox_close(struct Context *ctx)
 {
@@ -2477,7 +2458,6 @@ static int nm_mbox_close(struct Context *ctx)
   for (int i = 0; i < ctx->msgcount; i++)
   {
     struct Header *h = ctx->hdrs[i];
-
     if (h)
     {
       free_hdrdata(h->data);
@@ -2491,7 +2471,7 @@ static int nm_mbox_close(struct Context *ctx)
 }
 
 /**
- * nm_mbox_check - Check a notmuch mailbox for new mail
+ * nm_mbox_check - Implements MxOps::mbox_check()
  * @param ctx         Mailbox
  * @param index_hint  Remember our place in the index
  * @retval -1 Error
@@ -2619,11 +2599,7 @@ done:
 }
 
 /**
- * nm_mbox_sync - Sync a notmuch mailbox
- * @param ctx        Mailbox
- * @param index_hint Remember our place in the index
- * @retval  0 Success
- * @retval -1 Failure
+ * nm_mbox_sync - Implements MxOps::mbox_sync()
  */
 static int nm_mbox_sync(struct Context *ctx, int *index_hint)
 {
@@ -2706,12 +2682,7 @@ static int nm_mbox_sync(struct Context *ctx, int *index_hint)
 }
 
 /**
- * nm_msg_open - Open a message from a notmuch mailbox
- * @param ctx   Mailbox
- * @param msg   Message to open
- * @param msgno Index of message to open
- * @retval 0 Success
- * @retval 1 Error
+ * nm_msg_open - Implements MxOps::msg_open()
  */
 static int nm_msg_open(struct Context *ctx, struct Message *msg, int msgno)
 {
@@ -2735,24 +2706,18 @@ static int nm_msg_open(struct Context *ctx, struct Message *msg, int msgno)
 }
 
 /**
- * nm_msg_close - Close a message
- * @param ctx Mailbox
- * @param msg Message to close
- * @retval 0 Success
- * @retval 1 Error
+ * nm_msg_close - Implements MxOps::msg_close()
  */
 static int nm_msg_close(struct Context *ctx, struct Message *msg)
 {
   if (!msg)
-    return 1;
+    return -1;
   mutt_file_fclose(&(msg->fp));
   return 0;
 }
 
 /**
- * nm_msg_commit - Save the changes to a message
- * @param ctx Mailbox
- * @param msg Message to commit
+ * nm_msg_commit - Implements MxOps::msg_commit()
  * @retval -1 Always
  */
 static int nm_msg_commit(struct Context *ctx, struct Message *msg)
@@ -2763,9 +2728,7 @@ static int nm_msg_commit(struct Context *ctx, struct Message *msg)
 
 // clang-format off
 /**
- * struct mx_notmuch_ops - Mailbox API
- *
- * These functions are common to all mailbox types.
+ * struct mx_notmuch_ops - Mailbox callback functions for Notmuch mailboxes
  */
 struct MxOps mx_notmuch_ops = {
   .mbox_open        = nm_mbox_open, /* calls init_context() */
diff --git a/mx.h b/mx.h
index 862286f8e4f6e19f2eee4536df3b2d9ea7123421..1b1f3edeae42de6d614241b85bd80bb6c42426b7 100644 (file)
--- a/mx.h
+++ b/mx.h
@@ -37,28 +37,104 @@ struct Message;
 struct stat;
 
 /**
- * struct MxOps - a structure to store operations on a mailbox
+ * struct MxOps - The Mailbox API
  *
- * The following operations are mandatory:
- *  - open
- *  - close
- *  - check
- *
- * Optional operations
- *  - open_new_msg
+ * Each backend provides a set of functions through which the mailbox, messages
+ * and tags are manipulated.
  */
 struct MxOps
 {
+  /**
+   * mbox_check - Check for new mail
+   * @param ctx Mailbox
+   * @param index_hint Remember our place in the index
+   * @retval >0 Success, e.g. #MUTT_REOPENED
+   * @retval -1 Error
+   */
   int (*mbox_open)       (struct Context *ctx);
+  /**
+   * mbox_open - Open a mailbox
+   * @param ctx Mailbox to open
+   * @retval  0 Success
+   * @retval -1 Error
+   */
   int (*mbox_open_append)(struct Context *ctx, int flags);
+  /**
+   * mbox_open_append - Open a mailbox for appending
+   * @param ctx   Mailbox to open
+   * @param flags e.g. #MUTT_READONLY
+   * @retval  0 Success
+   * @retval -1 Failure
+   */
   int (*mbox_check)      (struct Context *ctx, int *index_hint);
+  /**
+   * mbox_sync - Save changes to the mailbox
+   * @param ctx        Mailbox to sync
+   * @param index_hint Remember our place in the index
+   * @retval  0 Success
+   * @retval -1 Failure
+   */
   int (*mbox_sync)       (struct Context *ctx, int *index_hint);
+  /**
+   * mbox_close - Close a mailbox
+   * @param ctx Mailbox to close
+   * @retval  0 Success
+   * @retval -1 Failure
+   */
   int (*mbox_close)      (struct Context *ctx);
+  /**
+   * msg_open - Open an email message in mailbox
+   * @param ctx   Mailbox
+   * @param msg   Message to open
+   * @param msgno Index of message to open
+   * @retval 0 Success
+   * @retval 1 Error
+   */
   int (*msg_open)        (struct Context *ctx, struct Message *msg, int msgno);
+  /**
+   * msg_open_new - Open a new message in a mailbox
+   * @param ctx Mailbox
+   * @param msg  Message to open
+   * @param hdr Email header
+   * @retval  0 Success
+   * @retval -1 Failure
+   */
   int (*msg_open_new)    (struct Context *ctx, struct Message *msg, struct Header *hdr);
+  /**
+   * msg_commit - Save changes to an email
+   * @param ctx Mailbox
+   * @param msg Message to commit
+   * @retval  0 Success
+   * @retval -1 Failure
+   */
   int (*msg_commit)      (struct Context *ctx, struct Message *msg);
+  /**
+   * msg_close - Close an email
+   * @param ctx Mailbox
+   * @param msg Message to close
+   * @retval  0 Success
+   * @retval -1 Failure
+   */
   int (*msg_close)       (struct Context *ctx, struct Message *msg);
+  /**
+   * tags_commit - Save the tags to a message
+   * @param ctx Mailbox
+   * @param hdr Email Header
+   * @param buf Buffer containing tags
+   * @retval  0 Success
+   * @retval -1 Failure
+   */
   int (*tags_edit)       (struct Context *ctx, const char *tags, char *buf, size_t buflen);
+  /**
+   * tags_edit - Prompt and validate new messages tags
+   * @param ctx    Mailbox
+   * @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
+   */
   int (*tags_commit)     (struct Context *ctx, struct Header *hdr, char *buf);
 };
 
diff --git a/nntp.c b/nntp.c
index 7e1020a1a393bfb666460c2f325900c730910334..2713d6561d0ba0112413b902fa95b77feb9e0b84 100644 (file)
--- a/nntp.c
+++ b/nntp.c
@@ -1478,10 +1478,7 @@ static int nntp_fetch_headers(struct Context *ctx, void *hc, anum_t first,
 }
 
 /**
- * nntp_mbox_open - Open newsgroup
- * @param ctx Mailbox
- * @retval  0 Success
- * @retval -1 Failure
+ * nntp_mbox_open - Implements MxOps::mbox_open()
  */
 static int nntp_mbox_open(struct Context *ctx)
 {
@@ -1615,12 +1612,7 @@ static int nntp_mbox_open(struct Context *ctx)
 }
 
 /**
- * nntp_msg_open - Fetch message
- * @param ctx   Mailbox
- * @param msg   Message to fetch
- * @param msgno Message number
- * @retval  0 Success
- * @retval -1 Failure
+ * nntp_msg_open - Implements MxOps::msg_open()
  */
 static int nntp_msg_open(struct Context *ctx, struct Message *msg, int msgno)
 {
@@ -1743,11 +1735,9 @@ static int nntp_msg_open(struct Context *ctx, struct Message *msg, int msgno)
 }
 
 /**
- * nntp_msg_close - Close message
- * @param ctx Mailbox
- * @param msg Message to close
- * @retval 0   Success
- * @retval EOF Error, see errno
+ * nntp_msg_close - Implements MxOps::msg_close()
+ *
+ * @note May also return EOF Failure, see errno
  */
 static int nntp_msg_close(struct Context *ctx, struct Message *msg)
 {
@@ -2098,7 +2088,7 @@ static int check_mailbox(struct Context *ctx)
 }
 
 /**
- * nntp_mbox_check - Check current newsgroup for new articles
+ * nntp_mbox_check - Implements MxOps::mbox_check()
  * @param ctx        Mailbox
  * @param index_hint Current message (UNUSED)
  * @retval #MUTT_REOPENED Articles have been renumbered or removed from server
@@ -2119,11 +2109,7 @@ static int nntp_mbox_check(struct Context *ctx, int *index_hint)
 }
 
 /**
- * nntp_mbox_sync - Save changes to .newsrc and cache
- * @param ctx        Mailbox
- * @param index_hint Current message (UNUSED)
- * @retval  0 Success
- * @retval -1 Failure
+ * nntp_mbox_sync - Implements MxOps::mbox_sync()
  *
  * @note May also return values from check_mailbox()
  */
@@ -2185,8 +2171,7 @@ static int nntp_mbox_sync(struct Context *ctx, int *index_hint)
 }
 
 /**
- * nntp_mbox_close - Free up memory associated with the newsgroup context
- * @param ctx Mailbox
+ * nntp_mbox_close - Implements MxOps::mbox_close()
  * @retval 0 Always
  */
 static int nntp_mbox_close(struct Context *ctx)
@@ -2592,6 +2577,9 @@ int nntp_check_children(struct Context *ctx, const char *msgid)
 }
 
 // clang-format off
+/**
+ * struct mx_nntp_ops - Mailbox callback functions for NNTP mailboxes
+ */
 struct MxOps mx_nntp_ops = {
   .mbox_open        = nntp_mbox_open,
   .mbox_open_append = NULL,
diff --git a/pop.c b/pop.c
index 605cddc38b922adfa0b95e0cec10ef3dc9a2b04d..a9358563fb0799b84fec05465c48b724a86f6864 100644 (file)
--- a/pop.c
+++ b/pop.c
@@ -1035,7 +1035,7 @@ fail:
 
 // clang-format off
 /**
- * mx_pop_ops - Mailbox callback functions
+ * mx_pop_ops - Mailbox callback functions for POP mailboxes
  */
 struct MxOps mx_pop_ops = {
   .mbox_open        = pop_open_mailbox,