]> granicus.if.org Git - neomutt/commitdiff
doxygen: doc some more functions
authorRichard Russon <rich@flatcap.org>
Tue, 18 Jul 2017 22:46:39 +0000 (23:46 +0100)
committerRichard Russon <rich@flatcap.org>
Tue, 18 Jul 2017 22:46:39 +0000 (23:46 +0100)
mutt_notmuch.c
rfc1524.c
sidebar.c

index 0693ab3beb2669a41f7a90fcbdf0c2c873da7ca5..e18a552a2d73accd34576bf44a6d0c764386f2ab 100644 (file)
@@ -204,6 +204,9 @@ static void debug_print_tags(notmuch_message_t *msg)
 /**
  * url_free_tags - Free a list of tags
  * @param tags List of tags
+ *
+ * Tags are stored as a singly-linked list.
+ * Free all the strings and the list, itself.
  */
 static void url_free_tags(struct UriTag *tags)
 {
@@ -302,6 +305,13 @@ err:
   return false;
 }
 
+/**
+ * free_tag_list - Free a list of tags
+ * @param tag_list List of tags
+ *
+ * Take a nm_hdrtag struct (a singly-linked list) and free the attached strings
+ * and the list itself.
+ */
 static void free_tag_list(struct NmHdrTag **tag_list)
 {
   struct NmHdrTag *tmp = NULL;
@@ -317,6 +327,14 @@ static void free_tag_list(struct NmHdrTag **tag_list)
   *tag_list = 0;
 }
 
+/**
+ * free_hdrdata - Free header data attached to an email
+ * @param data Header data
+ *
+ * Each email can have an attached nm_hdrdata struct, which contains things
+ * like the tags (labels).  This function frees all the resources and the
+ * nm_hdrdata struct itself.
+ */
 static void free_hdrdata(struct NmHdrData *data)
 {
   if (!data)
@@ -332,6 +350,14 @@ static void free_hdrdata(struct NmHdrData *data)
   FREE(&data);
 }
 
+/**
+ * free_ctxdata - Free data attached to the context
+ * @param data A mailbox CONTEXT
+ *
+ * The nm_ctxdata struct stores global NotMuch data, such as the connection to
+ * the database.  This function will close the database, free the resources and
+ * the struct itself.
+ */
 static void free_ctxdata(struct NmCtxData *data)
 {
   if (!data)
@@ -353,6 +379,14 @@ static void free_ctxdata(struct NmCtxData *data)
   FREE(&data);
 }
 
+/**
+ * new_ctxdata - Create a new nm_ctxdata object from a query
+ * @param uri NotMuch query string
+ * @return a new nm_ctxdata struct
+ *
+ * A new nm_ctxdata struct is created, then the query is parsed and saved
+ * within it.  This should be freed using free_ctxdata().
+ */
 static struct NmCtxData *new_ctxdata(char *uri)
 {
   struct NmCtxData *data = NULL;
@@ -375,6 +409,17 @@ static struct NmCtxData *new_ctxdata(char *uri)
   return data;
 }
 
+/**
+ * init_context - Add NotMuch data to the Context
+ * @param ctx A mailbox CONTEXT
+ * @return
+ * *  0 Success
+ * * -1 Error: Bad format
+ *
+ * Create a new nm_ctxdata struct and add it CONTEXT::data.
+ * NotMuch-specific data will be stored in this struct.
+ * This struct can be freed using free_hdrdata().
+ */
 static int init_context(struct Context *ctx)
 {
   if (!ctx || (ctx->magic != MUTT_NOTMUCH))
@@ -706,6 +751,14 @@ static int release_db(struct NmCtxData *data)
   return -1;
 }
 
+/**
+ * db_trans_begin - Start a NotMuch database transaction
+ * @param data Header data
+ * @return
+ * * < 0 = error
+ * * 1 = new transaction started
+ * * 0 = already within transaction
+ */
 static int db_trans_begin(struct NmCtxData *data)
 {
   if (!data || !data->db)
@@ -739,11 +792,27 @@ static int db_trans_end(struct NmCtxData *data)
   return 0;
 }
 
+/**
+ * is_longrun - Is NotMuch in the middle of a long-running transaction
+ * @param data Header data
+ * @return true if it is
+ */
 static int is_longrun(struct NmCtxData *data)
 {
   return data && data->longrun;
 }
 
+/**
+ * get_database_mtime - Get the database modification time
+ * @param[in]  data  Struct holding database info
+ * @param[out] mtime Save the modification time
+ * @return
+ * *  0 Success (result in mtime)
+ * * -1 Error
+ *
+ * Get the "mtime" (modification time) of the database file.
+ * This is the time of the last update.
+ */
 static int get_database_mtime(struct NmCtxData *data, time_t *mtime)
 {
   char path[_POSIX_PATH_MAX];
@@ -969,6 +1038,13 @@ static void deinit_header(struct Header *h)
   }
 }
 
+/**
+ * nm2mutt_message_id - converts notmuch message Id to mutt message Id
+ * @param id NotMuch ID to convert
+ * @return Mutt message ID
+ *
+ * Caller must free the Mutt Message ID
+ */
 static char *nm2mutt_message_id(const char *id)
 {
   size_t sz;
@@ -1194,6 +1270,11 @@ done:
   FREE(&newpath);
 }
 
+/**
+ * append_replies - add all the replies to a given messages into the display
+ *
+ * Careful, this calls itself recursively to make sure we get everything.
+ */
 static void append_replies(struct Context *ctx, notmuch_query_t *q,
                            notmuch_message_t *top, int dedup)
 {
@@ -1210,6 +1291,12 @@ static void append_replies(struct Context *ctx, notmuch_query_t *q,
   }
 }
 
+/**
+ * append_thread - add each top level reply in the thread
+ *
+ * add each top level reply in the thread, and then add each reply to the top
+ * level replies
+ */
 static void append_thread(struct Context *ctx, notmuch_query_t *q,
                           notmuch_thread_t *thread, int dedup)
 {
@@ -1375,6 +1462,13 @@ static int update_tags(notmuch_message_t *msg, const char *tags)
   return 0;
 }
 
+/**
+ * update_header_flags - Update the header flags
+ *
+ * TODO: extract parsing of string to separate function, join
+ * update_header_tags and update_header_flags, which are given an array of
+ * tags.
+ */
 static int update_header_flags(struct Context *ctx, struct Header *hdr, const char *tags)
 {
   char *tag = NULL, *end = NULL, *p = NULL;
@@ -1845,7 +1939,7 @@ bool nm_normalize_uri(char *new_uri, const char *orig_uri, size_t new_uri_sz)
 void nm_query_window_forward(void)
 {
   if (NotmuchQueryWindowCurrentPosition != 0)
-    NotmuchQueryWindowCurrentPosition -= 1;
+    NotmuchQueryWindowCurrentPosition--;
 
   mutt_debug(2, "nm_query_window_forward (%d)\n", NotmuchQueryWindowCurrentPosition);
 }
@@ -1860,7 +1954,7 @@ void nm_query_window_forward(void)
  */
 void nm_query_window_backward(void)
 {
-  NotmuchQueryWindowCurrentPosition += 1;
+  NotmuchQueryWindowCurrentPosition++;
   mutt_debug(2, "nm_query_window_backward (%d)\n", NotmuchQueryWindowCurrentPosition);
 }
 
@@ -2136,6 +2230,11 @@ done:
   return rc;
 }
 
+/**
+ * nm_get_all_tags - Fill a list with all notmuch tags
+ *
+ * If tag_list is NULL, just count the tags.
+ */
 int nm_get_all_tags(struct Context *ctx, char **tag_list, int *tag_count)
 {
   struct NmCtxData *data = get_ctxdata(ctx);
@@ -2179,6 +2278,14 @@ done:
 }
 
 
+/**
+ * nm_open_mailbox - Open a notmuch virtual mailbox
+ * @param ctx A mailbox CONTEXT
+ * @return
+ * *  0 Success
+ * * -1 Error
+ */
+
 static int nm_open_mailbox(struct Context *ctx)
 {
   notmuch_query_t *q = NULL;
@@ -2226,6 +2333,13 @@ static int nm_open_mailbox(struct Context *ctx)
   return rc;
 }
 
+/**
+ * nm_close_mailbox - Close a notmuch virtual mailbox
+ * @param ctx A mailbox CONTEXT
+ * @return
+ * *  0 Success
+ * * -1 Error
+ */
 static int nm_close_mailbox(struct Context *ctx)
 {
   if (!ctx || (ctx->magic != MUTT_NOTMUCH))
@@ -2247,6 +2361,17 @@ static int nm_close_mailbox(struct Context *ctx)
   return 0;
 }
 
+/**
+ * nm_check_mailbox - Check a notmuch mailbox for new mail
+ * @param ctx         A mailbox CONTEXT
+ * @param index_hint  Remeber our place in the index
+ * @return
+ * * -1 Error
+ * *  0 QWQ
+ * * #MUTT_NEW_MAIL - new mail has arrived
+ * * #MUTT_REOPENED - mailbox closed and reopened
+ * * #MUTT_FLAGS - QWQ
+ */
 static int nm_check_mailbox(struct Context *ctx, int *index_hint)
 {
   struct NmCtxData *data = get_ctxdata(ctx);
@@ -2307,8 +2432,8 @@ static int nm_check_mailbox(struct Context *ctx, int *index_hint)
     /* message already exists, merge flags */
     h->active = true;
 
-    /* check to see if the message has moved to a different
-     * subdirectory.  If so, update the associated filename.
+    /* Check to see if the message has moved to a different subdirectory.
+     * If so, update the associated filename.
      */
     new = get_message_last_filename(m);
     header_get_fullpath(h, old, sizeof(old));
@@ -2362,6 +2487,11 @@ done:
                                                         new_flags ? MUTT_FLAGS : 0;
 }
 
+/**
+ * nm_sync_mailbox - Sync a notmuch mailbox
+ * @param ctx        A mailbox CONTEXT
+ * @param index_hint Remember our place in the index
+ */
 static int nm_sync_mailbox(struct Context *ctx, int *index_hint)
 {
   struct NmCtxData *data = get_ctxdata(ctx);
@@ -2442,6 +2572,15 @@ static int nm_sync_mailbox(struct Context *ctx, int *index_hint)
   return rc;
 }
 
+/**
+ * nm_open_message - Open a message from a notmuch mailbox
+ * @param ctx   A mailbox CONTEXT
+ * @param msg   Message to open
+ * @param msgno Index of message to open
+ * @return
+ * * 0 Success
+ * * 1 Error
+ */
 static int nm_open_message(struct Context *ctx, struct Message *msg, int msgno)
 {
   if (!ctx || !msg)
@@ -2462,6 +2601,14 @@ static int nm_open_message(struct Context *ctx, struct Message *msg, int msgno)
   return !msg->fp;
 }
 
+/**
+ * nm_close_message - Close a message
+ * @param ctx A mailbox CONTEXT
+ * @param msg Message to close
+ * @return
+ * * 0 Success
+ * * 1 Error
+ */
 static int nm_close_message(struct Context *ctx, struct Message *msg)
 {
   if (!msg)
index 0882855bc8d6b0d00fa5126baf0b33a743601f06..d381c63290b9f355a1dd77fe9f8d93f3a9db8bed 100644 (file)
--- a/rfc1524.c
+++ b/rfc1524.c
@@ -384,7 +384,7 @@ void rfc1524_free_entry(struct Rfc1524MailcapEntry **entry)
  * rfc1524_mailcap_lookup - Find given type in the list of mailcap files
  * @param a      Message body
  * @param type   Text type in "type/subtype" format
- * @param struct Rfc1524MailcapEntry pointer to an struct Rfc1524MailcapEntry to populate with results
+ * @param entry  struct Rfc1524MailcapEntry to populate with results
  * @param opt    Type of mailcap entry to lookup
  * @return
  * * 1 on success. If *entry is not NULL it poplates it with the mailcap entry
index 791522854273559f79d288681c80015ee3bc2868..e6e5f14c59ce73e949e62dc6fa7eac26f0b9ee09 100644 (file)
--- a/sidebar.c
+++ b/sidebar.c
@@ -54,28 +54,28 @@ static short PreviousSort = SORT_ORDER; /* sidebar_sort_method */
  */
 struct SbEntry
 {
-  char box[STRING]; /**< formatted mailbox name */
-  struct Buffy *buffy;
-  bool is_hidden;
+  char box[STRING];    /**< formatted mailbox name */
+  struct Buffy *buffy; /**< Mailbox this represents */
+  bool is_hidden;      /**< Don't show, e.g. $sidebar_new_mail_only */
 };
 
 static int EntryCount = 0;
 static int EntryLen = 0;
 static struct SbEntry **Entries = NULL;
 
-static int TopIndex = -1; /* First mailbox visible in sidebar */
-static int OpnIndex = -1; /* Current (open) mailbox */
-static int HilIndex = -1; /* Highlighted mailbox */
-static int BotIndex = -1; /* Last mailbox visible in sidebar */
+static int TopIndex = -1; /**< First mailbox visible in sidebar */
+static int OpnIndex = -1; /**< Current (open) mailbox */
+static int HilIndex = -1; /**< Highlighted mailbox */
+static int BotIndex = -1; /**< Last mailbox visible in sidebar */
 
 /**
  * enum DivType - Source of the sidebar divider character
  */
 enum DivType
 {
-  SB_DIV_USER,
-  SB_DIV_ASCII,
-  SB_DIV_UTF8
+  SB_DIV_USER,  /**< User configured using $sidebar_divider_char */
+  SB_DIV_ASCII, /**< An ASCII vertical bar (pipe) */
+  SB_DIV_UTF8   /**< A unicode line-drawing character */
 };
 
 /**
@@ -83,23 +83,23 @@ enum DivType
  */
 enum SidebarSrc
 {
-  SB_SRC_INCOMING,
-  SB_SRC_VIRT,
+  SB_SRC_INCOMING, /**< Display real mailboxes */
+  SB_SRC_VIRT,     /**< Display virtual mailboxes */
 } sidebar_source = SB_SRC_INCOMING;
 
 /**
  * cb_format_str - Create the string to show in the sidebar
- * @param dest        Buffer in which to save string
- * @param destlen     Buffer length
- * @param col         Starting column, UNUSED
- * @param cols        Maximum columns, UNUSED
- * @param op          printf-like operator, e.g. 'B'
- * @param src         printf-like format string
- * @param prefix      Field formatting string, UNUSED
- * @param ifstring    If condition is met, display this string
- * @param elsestring  Otherwise, display this string
- * @param data        Pointer to our sidebar_entry
- * @param flags       Format flags, e.g. MUTT_FORMAT_OPTIONAL
+ * @param[out] dest        Buffer in which to save string
+ * @param[in]  destlen     Buffer length
+ * @param[in]  col         Starting column, UNUSED
+ * @param[in]  cols        Maximum columns, UNUSED
+ * @param[in]  op          printf-like operator, e.g. 'B'
+ * @param[in]  src         printf-like format string
+ * @param[in]  prefix      Field formatting string, UNUSED
+ * @param[in]  ifstring    If condition is met, display this string
+ * @param[in]  elsestring  Otherwise, display this string
+ * @param[in]  data        Pointer to our sidebar_entry
+ * @param[in]  flags       Format flags, e.g. MUTT_FORMAT_OPTIONAL
  * @return src (unchanged)
  *
  * cb_format_str is a callback function for mutt_expando_format.  It understands
@@ -234,11 +234,11 @@ static const char *cb_format_str(char *dest, size_t destlen, size_t col, int col
 
 /**
  * make_sidebar_entry - Turn mailbox data into a sidebar string
- * @param buf     Buffer in which to save string
- * @param buflen  Buffer length
- * @param width   Desired width in screen cells
- * @param box     Mailbox name
- * @param sbe     Mailbox object
+ * @param[out] buf     Buffer in which to save string
+ * @param[in]  buflen  Buffer length
+ * @param[in]  width   Desired width in screen cells
+ * @param[in]  box     Mailbox name
+ * @param[in]  sbe     Mailbox object
  *
  * Take all the relevant mailbox data and the desired screen width and then get
  * mutt_expando_format to do the actual work. mutt_expando_format will callback to
@@ -334,11 +334,11 @@ static int cb_qsort_sbe(const void *a, const void *b)
  *
  * For each SbEntry in the Entries array, check whether we should display it.
  * This is determined by several criteria.  If the Buffy:
- *      is the currently open mailbox
- *      is the currently highlighted mailbox
- *      has unread messages
- *      has flagged messages
- *      is whitelisted
+ * * is the currently open mailbox
+ * * is the currently highlighted mailbox
+ * * has unread messages
+ * * has flagged messages
+ * * is whitelisted
  */
 static void update_entries_visibility(void)
 {
@@ -662,8 +662,8 @@ static bool prepare_sidebar(int page_size)
  * @param num_rows   Height of the Sidebar
  * @param num_cols   Width of the Sidebar
  * @return
- * *    0:  Empty string
- * *    n:  Character occupies n screen columns
+ * * 0: Empty string
+ * * n: Character occupies n screen columns
  *
  * Draw a divider using characters from the config option "sidebar_divider_char".
  * This can be an ASCII or Unicode character.
@@ -775,7 +775,7 @@ static void fill_empty_space(int first_row, int num_rows, int div_width, int num
 }
 
 /**
- * draw_sidebar - Write out a list of mailboxes, on the left
+ * draw_sidebar - Write out a list of mailboxes, in a panel
  * @param num_rows   Height of the Sidebar
  * @param num_cols   Width of the Sidebar
  * @param div_width  Width in screen characters taken by the divider