From: Richard Russon Date: Tue, 18 Jul 2017 22:46:39 +0000 (+0100) Subject: doxygen: doc some more functions X-Git-Tag: neomutt-20170907~61 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=95cc1873dd836afacaeaddd939f1a096b49e9bad;p=neomutt doxygen: doc some more functions --- diff --git a/mutt_notmuch.c b/mutt_notmuch.c index 0693ab3be..e18a552a2 100644 --- a/mutt_notmuch.c +++ b/mutt_notmuch.c @@ -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) diff --git a/rfc1524.c b/rfc1524.c index 0882855bc..d381c6329 100644 --- 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 diff --git a/sidebar.c b/sidebar.c index 791522854..e6e5f14c5 100644 --- 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