update format function comments

diff --git a/addrbook.c b/addrbook.c
index 55bc9d581a7262a8e4b2e92676d83eaff5ba5a5b..793f47bf49bdde9b17b06a6bcd740be0c0eb3c44 100644 (file)
--- a/addrbook.c
+++ b/addrbook.c
@@ -47,6 +47,31 @@ static const struct Mapping AliasHelp[] = {
   { N_("Help"), OP_HELP },      { NULL, 0 },
 };
 
+/**
+ * alias_format_str - Format a string for the alias list
+ * @param[out] buf      Buffer in which to save string
+ * @param[in]  buflen   Buffer length
+ * @param[in]  col      Starting column
+ * @param[in]  cols     Number of screen columns
+ * @param[in]  op       printf-like operator, e.g. 't'
+ * @param[in]  src      printf-like format string
+ * @param[in]  prec     Field precision, e.g. "-3.4"
+ * @param[in]  if_str   If condition is met, display this string
+ * @param[in]  else_str Otherwise, display this string
+ * @param[in]  data     Pointer to the mailbox Context
+ * @param[in]  flags    Format flags
+ * @retval src (unchanged)
+ *
+ * alias_format_str() is a callback function for mutt_expando_format().
+ *
+ * | Expando | Description
+ * |:--------|:--------------------------------------------------------
+ * | \%a     | Alias name
+ * | \%f     | Flags - currently, a 'd' for an alias marked for deletion
+ * | \%n     | Index number
+ * | \%r     | Address which alias expands to
+ * | \%t     | Character which indicates if the alias is tagged for inclusion
+ */
 static const char *alias_format_str(char *buf, size_t buflen, size_t col, int cols,
                                     char op, const char *src, const char *prec,
                                     const char *if_str, const char *else_str,
@@ -83,6 +108,13 @@ static const char *alias_format_str(char *buf, size_t buflen, size_t col, int co
   return src;
 }
 
+/**
+ * alias_entry - Format a menu item for the alias list
+ * @param[out] buf    Buffer in which to save string
+ * @param[in]  buflen Buffer length
+ * @param[in]  menu   Menu containing aliases
+ * @param[in]  num    Index into the menu
+ */
 static void alias_entry(char *buf, size_t buflen, struct Menu *menu, int num)
 {
   mutt_expando_format(buf, buflen, 0, MuttIndexWindow->cols, NONULL(AliasFormat), alias_format_str,

diff --git a/browser.c b/browser.c
index b59a97e9ef0290f9df4016fe5cca326086a3a671..cab30c9d4bb981d014ce88202eb98dc8b4595031 100644 (file)
--- a/browser.c
+++ b/browser.c
@@ -273,6 +273,39 @@ static int link_is_dir(const char *folder, const char *path)
     return 0;
 }
 
+/**
+ * folder_format_str - Format a string for the folder browser
+ * @param[out] buf      Buffer in which to save string
+ * @param[in]  buflen   Buffer length
+ * @param[in]  col      Starting column
+ * @param[in]  cols     Number of screen columns
+ * @param[in]  op       printf-like operator, e.g. 't'
+ * @param[in]  src      printf-like format string
+ * @param[in]  prec     Field precision, e.g. "-3.4"
+ * @param[in]  if_str   If condition is met, display this string
+ * @param[in]  else_str Otherwise, display this string
+ * @param[in]  data     Pointer to the mailbox Context
+ * @param[in]  flags    Format flags
+ * @retval src (unchanged)
+ *
+ * folder_format_str() is a callback function for mutt_expando_format().
+ *
+ * | Expando | Description
+ * |:--------|:--------------------------------------------------------
+ * | \%C     | Current file number
+ * | \%d     | Date/time folder was last modified
+ * | \%D     | Date/time folder was last modified using $$date_format.
+ * | \%F     | File permissions
+ * | \%f     | Filename (with suffix '/', '@' or '*')
+ * | \%g     | Group name (or numeric gid, if missing)
+ * | \%l     | Number of hard links
+ * | \%m     | Number of messages in the mailbox *
+ * | \%N     | N if mailbox has new mail, blank otherwise
+ * | \%n     | Number of unread messages in the mailbox *
+ * | \%s     | Size in bytes
+ * | \%t     | '*' if the file is tagged, blank otherwise
+ * | \%u     | Owner name (or numeric uid, if missing)
+ */
 static const char *folder_format_str(char *buf, size_t buflen, size_t col, int cols,
                                      char op, const char *src, const char *prec,
                                      const char *if_str, const char *else_str,
@@ -496,6 +529,33 @@ static const char *folder_format_str(char *buf, size_t buflen, size_t col, int c
 }
 
 #ifdef USE_NNTP
+/**
+ * group_index_format_str - Format a string for the newsgroup menu
+ * @param[out] buf      Buffer in which to save string
+ * @param[in]  buflen   Buffer length
+ * @param[in]  col      Starting column
+ * @param[in]  cols     Number of screen columns
+ * @param[in]  op       printf-like operator, e.g. 't'
+ * @param[in]  src      printf-like format string
+ * @param[in]  prec     Field precision, e.g. "-3.4"
+ * @param[in]  if_str   If condition is met, display this string
+ * @param[in]  else_str Otherwise, display this string
+ * @param[in]  data     Pointer to the mailbox Context
+ * @param[in]  flags    Format flags
+ * @retval src (unchanged)
+ *
+ * group_index_format_str() is a callback function for mutt_expando_format().
+ *
+ * | Expando | Description
+ * |:--------|:--------------------------------------------------------
+ * | \%C     | Current newsgroup number
+ * | \%d     | Description of newsgroup (becomes from server)
+ * | \%f     | Newsgroup name
+ * | \%M     | - if newsgroup not allowed for direct post (moderated for example)
+ * | \%N     | N if newsgroup is new, u if unsubscribed, blank otherwise
+ * | \%n     | Number of new articles in newsgroup
+ * | \%s     | Number of unread articles in newsgroup
+ */
 static const char *group_index_format_str(char *buf, size_t buflen, size_t col, int cols,
                                           char op, const char *src, const char *prec,
                                           const char *if_str, const char *else_str,
@@ -896,6 +956,13 @@ static int select_vfolder_search(struct Menu *menu, regex_t *re, int n)
 }
 #endif
 
+/**
+ * folder_entry - Format a menu item for the folder browser
+ * @param[out] buf    Buffer in which to save string
+ * @param[in]  buflen Buffer length
+ * @param[in]  menu   Menu containing aliases
+ * @param[in]  num    Index into the menu
+ */
 static void folder_entry(char *buf, size_t buflen, struct Menu *menu, int num)
 {
   struct Folder folder;
@@ -916,6 +983,13 @@ static void folder_entry(char *buf, size_t buflen, struct Menu *menu, int num)
 }
 
 #ifdef USE_NOTMUCH
+/**
+ * vfolder_entry - Format a menu item for the virtual folder list
+ * @param[out] buf    Buffer in which to save string
+ * @param[in]  buflen Buffer length
+ * @param[in]  menu   Menu containing aliases
+ * @param[in]  num    Index into the menu
+ */
 static void vfolder_entry(char *buf, size_t buflen, struct Menu *menu, int num)
 {
   struct Folder folder;

diff --git a/compose.c b/compose.c
index 7c0dcbe7487c0ad4ae1aedae0ad29160770bbc77..71711989b6006279f9c6f655fdb40a81dde211f0 100644 (file)
--- a/compose.c
+++ b/compose.c
@@ -224,6 +224,13 @@ static void init_header_padding(void)
   }
 }
 
+/**
+ * snd_entry - Format a menu item for the attachment list
+ * @param[out] buf    Buffer in which to save string
+ * @param[in]  buflen Buffer length
+ * @param[in]  menu   Menu containing aliases
+ * @param[in]  num    Index into the menu
+ */
 static void snd_entry(char *buf, size_t buflen, struct Menu *menu, int num)
 {
   struct AttachCtx *actx = (struct AttachCtx *) menu->data;
@@ -680,15 +687,28 @@ static unsigned long cum_attachs_size(struct Menu *menu)
 }
 
 /**
- * compose_format_str - Format strings like printf()
+ * compose_format_str - Create the status bar string for compose mode
+ * @param[out] buf      Buffer in which to save string
+ * @param[in]  buflen   Buffer length
+ * @param[in]  col      Starting column
+ * @param[in]  cols     Number of screen columns
+ * @param[in]  op       printf-like operator, e.g. 't'
+ * @param[in]  src      printf-like format string
+ * @param[in]  prec     Field precision, e.g. "-3.4"
+ * @param[in]  if_str   If condition is met, display this string
+ * @param[in]  else_str Otherwise, display this string
+ * @param[in]  data     Pointer to the mailbox Context
+ * @param[in]  flags    Format flags
+ * @retval src (unchanged)
  *
- * * \%a Total number of attachments
- * * \%h ShortHostname  [option]
- * * \%l Approx. length of current message (in bytes)
- * * \%v NeoMutt version
+ * compose_format_str() is a callback function for mutt_expando_format().
  *
- * This function is similar to status_format_str().  Look at that function for
- * help when modifying this function.
+ * | Expando | Description
+ * |:--------|:--------------------------------------------------------
+ * | \%a     | Total number of attachments
+ * | \%h     | Local hostname
+ * | \%l     | Approximate size (in bytes) of the current message
+ * | \%v     | NeoMutt version string
  */
 static const char *compose_format_str(char *buf, size_t buflen, size_t col, int cols,
                                       char op, const char *src, const char *prec,

diff --git a/compress.c b/compress.c
index ada3011ede56fd0cdc7afa56854f20a4a470a619..bd806bb1baaded35daa5a2964eca895701badf19 100644 (file)
--- a/compress.c
+++ b/compress.c
@@ -329,22 +329,26 @@ static char *escape_path(char *src)
 }
 
 /**
- * compress_format_str - Expand the filenames in the command string
- * @param buf        Buffer in which to save string
- * @param buflen     Buffer length
- * @param col         Starting column, UNUSED
- * @param cols        Number of screen columns, UNUSED
- * @param op          printf-like operator, e.g. 't'
- * @param src         printf-like format string
- * @param prec         Field formatting string, UNUSED
- * @param if_str    If condition is met, display this string, UNUSED
- * @param else_str  Otherwise, display this string, UNUSED
- * @param data        Pointer to the mailbox Context
- * @param flags       Format flags, UNUSED
+ * compress_format_str - Expand the filenames in a command string
+ * @param[out] buf      Buffer in which to save string
+ * @param[in]  buflen   Buffer length
+ * @param[in]  col      Starting column
+ * @param[in]  cols     Number of screen columns
+ * @param[in]  op       printf-like operator, e.g. 't'
+ * @param[in]  src      printf-like format string
+ * @param[in]  prec     Field precision, e.g. "-3.4"
+ * @param[in]  if_str   If condition is met, display this string
+ * @param[in]  else_str Otherwise, display this string
+ * @param[in]  data     Pointer to the mailbox Context
+ * @param[in]  flags    Format flags
  * @retval src (unchanged)
  *
- * compress_format_str is a callback function for mutt_expando_format.  It understands
- * two operators. '%f' : 'from' filename, '%t' : 'to' filename.
+ * compress_format_str() is a callback function for mutt_expando_format().
+ *
+ * | Expando | Description
+ * |:--------|:--------------------------------------------------------
+ * | \%f     | Compressed file
+ * | \%t     | Plaintext, temporary file
  */
 static const char *compress_format_str(char *buf, size_t buflen, size_t col, int cols,
                                        char op, const char *src, const char *prec,

diff --git a/curs_lib.c b/curs_lib.c
index 3b1057273679fb709caf23dcb0d44afc37a2b721..38acbbfe2f9b17bdb33b4bb45aa5103c09804420 100644 (file)
--- a/curs_lib.c
+++ b/curs_lib.c
@@ -1152,8 +1152,17 @@ int mutt_addwch(wchar_t wc)
 
 /**
  * mutt_simple_format - Format a string, like snprintf()
+ * @param[out] buf       Buffer in which to save string
+ * @param[in]  buflen    Buffer length
+ * @param[in]  min_width Minimum width
+ * @param[in]  max_width Maximum width
+ * @param[in]  justify   Justification, e.g. #FMT_RIGHT
+ * @param[in]  pad_char  Padding character
+ * @param[in]  s         String to format
+ * @param[in]  n         Number of bytes of string to format
+ * @param[in]  arboreal  If true, string contains graphical tree characters
  *
- * This formats a string, a bit like snprintf (dest, destlen, "%-*.*s",
+ * This formats a string, a bit like snprintf(buf, buflen, "%-*.*s",
  * min_width, max_width, s), except that the widths refer to the number of
  * character cells when printed.
  */
@@ -1259,6 +1268,11 @@ void mutt_simple_format(char *buf, size_t buflen, int min_width, int max_width,
 
 /**
  * format_s_x - Format a string like snprintf()
+ * @param[out] buf      Buffer in which to save string
+ * @param[in]  buflen   Buffer length
+ * @param[in]  prec     Field precision, e.g. "-3.4"
+ * @param[in]  s        String to format
+ * @param[in]  arboreal  If true, string contains graphical tree characters
  *
  * This formats a string rather like
  *   snprintf (fmt, sizeof (fmt), "%%%ss", prec);
@@ -1296,11 +1310,25 @@ static void format_s_x(char *buf, size_t buflen, const char *prec, const char *s
                      mutt_str_strlen(s), arboreal);
 }
 
+/**
+ * mutt_format_s - Format a simple string
+ * @param[out] buf      Buffer in which to save string
+ * @param[in]  buflen   Buffer length
+ * @param[in]  prec     Field precision, e.g. "-3.4"
+ * @param[in]  s        String to format
+ */
 void mutt_format_s(char *buf, size_t buflen, const char *prec, const char *s)
 {
   format_s_x(buf, buflen, prec, s, 0);
 }
 
+/**
+ * mutt_format_s_tree - Format a simple string with tree characters
+ * @param[out] buf      Buffer in which to save string
+ * @param[in]  buflen   Buffer length
+ * @param[in]  prec     Field precision, e.g. "-3.4"
+ * @param[in]  s        String to format
+ */
 void mutt_format_s_tree(char *buf, size_t buflen, const char *prec, const char *s)
 {
   format_s_x(buf, buflen, prec, s, 1);

diff --git a/curs_main.c b/curs_main.c
index 686cc99b7c8fac25839e7abbebc6ab7665f7d757..4403580c9b7aa42927cff4f96e5e1831fa33c295 100644 (file)
--- a/curs_main.c
+++ b/curs_main.c
@@ -594,6 +594,13 @@ void mutt_ts_icon(char *str)
   fprintf(stderr, "\033]1;%s\007", str);
 }
 
+/**
+ * index_make_entry - Format a menu item for the index list
+ * @param[out] buf    Buffer in which to save string
+ * @param[in]  buflen Buffer length
+ * @param[in]  menu   Menu containing aliases
+ * @param[in]  num    Index into the menu
+ */
 void index_make_entry(char *buf, size_t buflen, struct Menu *menu, int num)
 {
   if (!Context || !menu || (num < 0) || (num >= Context->hdrmax))

diff --git a/hdrline.c b/hdrline.c
index d281870e0df79f9860fe7da8a9607d3ac76874d8..30e4f6408a7b06bb26a454e2ca4db4c82ab650cf 100644 (file)
--- a/hdrline.c
+++ b/hdrline.c
@@ -410,53 +410,72 @@ static bool thread_is_old(struct Context *ctx, struct Header *hdr)
 }
 
 /**
- * index_format_str - Format a string, like printf()
+ * index_format_str - Format a string for the index list
+ * @param[out] buf      Buffer in which to save string
+ * @param[in]  buflen   Buffer length
+ * @param[in]  col      Starting column
+ * @param[in]  cols     Number of screen columns
+ * @param[in]  op       printf-like operator, e.g. 't'
+ * @param[in]  src      printf-like format string
+ * @param[in]  prec     Field precision, e.g. "-3.4"
+ * @param[in]  if_str   If condition is met, display this string
+ * @param[in]  else_str Otherwise, display this string
+ * @param[in]  data     Pointer to the mailbox Context
+ * @param[in]  flags    Format flags
+ * @retval src (unchanged)
+ *
+ * index_format_str() is a callback function for mutt_expando_format().
  *
  * | Expando | Description
  * |:--------|:-----------------------------------------------------------------
- * | \%a     | address of author
- * | \%A     | reply-to address (if present; otherwise: address of author
- * | \%b     | filename of the originating folder
- * | \%B     | the list to which the letter was sent, or else the folder name (%b).
- * | \%c     | size of message in bytes
- * | \%C     | current message number
- * | \%d     | date and time of message using $date_format and sender's timezone
- * | \%D     | date and time of message using $date_format and local timezone
- * | \%e     | current message number in thread
- * | \%E     | number of messages in current thread
- * | \%f     | entire from line
- * | \%F     | like %n, unless from self
- * | \%g     | message tags (e.g. notmuch tags/imap flags)
- * | \%Gx    | individual message tag (e.g. notmuch tags/imap flags)
- * | \%i     | message-id
- * | \%I     | initials of author
- * | \%J     | message tags (if present, tree unfolded, and != parent's tags)
- * | \%K     | the list to which the letter was sent (if any; otherwise: empty)
- * | \%l     | number of lines in the message
- * | \%L     | like %F, except `lists' are displayed first
- * | \%m     | number of messages in the mailbox
- * | \%n     | name of author
- * | \%N     | score
- * | \%O     | like %L, except using address instead of name
- * | \%P     | progress indicator for builtin pager
- * | \%q     | newsgroup name (if compiled with NNTP support)
- * | \%r     | comma separated list of To: recipients
- * | \%R     | comma separated list of Cc: recipients
- * | \%s     | subject
- * | \%S     | short message status (e.g., N/O/D/!/r/-)
- * | \%t     | `to:' field (recipients)
+ * | \%a     | Address of author
+ * | \%A     | Reply-to address (if present; otherwise: address of author
+ * | \%b     | Filename of the originating folder
+ * | \%B     | The list to which the letter was sent, or else the folder name (%b).
+ * | \%C     | Current message number
+ * | \%c     | Size of message in bytes
+ * | \%D     | Date and time of message using $date_format and local timezone
+ * | \%d     | Date and time of message using $date_format and sender's timezone
+ * | \%e     | Current message number in thread
+ * | \%E     | Number of messages in current thread
+ * | \%f     | Entire from line
+ * | \%F     | Like %n, unless from self
+ * | \%g     | Message tags (e.g. notmuch tags/imap flags)
+ * | \%Gx    | Individual message tag (e.g. notmuch tags/imap flags)
+ * | \%H     | Spam attribute(s) of this message
+ * | \%I     | Initials of author
+ * | \%i     | Message-id
+ * | \%J     | Message tags (if present, tree unfolded, and != parent's tags)
+ * | \%K     | The list to which the letter was sent (if any; otherwise: empty)
+ * | \%L     | Like %F, except 'lists' are displayed first
+ * | \%l     | Number of lines in the message
+ * | \%M     | Number of hidden messages if the thread is collapsed
+ * | \%m     | Number of messages in the mailbox
+ * | \%n     | Name of author
+ * | \%N     | Score
+ * | \%O     | Like %L, except using address instead of name
+ * | \%P     | Progress indicator for builtin pager
+ * | \%q     | Newsgroup name (if compiled with NNTP support)
+ * | \%R     | Comma separated list of Cc: recipients
+ * | \%r     | Comma separated list of To: recipients
+ * | \%S     | Short message status (e.g., N/O/D/!/r/-)
+ * | \%s     | Subject
  * | \%T     | $to_chars
- * | \%u     | user (login) name of author
- * | \%v     | first name of author, unless from self
- * | \%W     | where user is (organization)
- * | \%x     | `x-comment-to:' field (if present and compiled with NNTP support)
- * | \%X     | number of MIME attachments
- * | \%y     | `x-label:' field (if present)
- * | \%Y     | `x-label:' field (if present, tree unfolded, and != parent's x-label)
- * | \%zs    | message status flags
- * | \%zc    | message crypto flags
- * | \%zt    | message tag flags
- * | \%Z     | combined message flags
+ * | \%t     | 'To:' field (recipients)
+ * | \%u     | User (login) name of author
+ * | \%v     | First name of author, unless from self
+ * | \%W     | Where user is (organization)
+ * | \%x     | 'X-Comment-To:' field (if present and compiled with NNTP support)
+ * | \%X     | Number of MIME attachments
+ * | \%y     | 'X-Label:' field (if present)
+ * | \%Y     | 'X-Label:' field (if present, tree unfolded, and != parent's x-label)
+ * | \%Z     | Combined message flags
+ * | \%zc    | Message crypto flags
+ * | \%zs    | Message status flags
+ * | \%zt    | Message tag flags
+ * | \%(fmt) | Date/time when the message was received
+ * | \%[fmt] | Message date/time converted to the local time zone
+ * | \%{fmt} | Message date/time converted to sender's time zone
  */
 static const char *index_format_str(char *buf, size_t buflen, size_t col, int cols,
                                     char op, const char *src, const char *prec,

diff --git a/init.h b/init.h
index c6db306c8f6f0e5e57360b63e565cfdc6eaf229e..58b838a58a7b7396d4406e93c9c03d9c70021e52 100644 (file)
--- a/init.h
+++ b/init.h
@@ -134,11 +134,11 @@ struct Option MuttVars[] = {
   ** Specifies the format of the data displayed for the ``$alias'' menu.  The
   ** following \fCprintf(3)\fP-style sequences are available:
   ** .dl
-  ** .dt %a .dd alias name
-  ** .dt %f .dd flags - currently, a ``d'' for an alias marked for deletion
-  ** .dt %n .dd index number
-  ** .dt %r .dd address which alias expands to
-  ** .dt %t .dd character which indicates if the alias is tagged for inclusion
+  ** .dt %a .dd Alias name
+  ** .dt %f .dd Flags - currently, a ``d'' for an alias marked for deletion
+  ** .dt %n .dd Index number
+  ** .dt %r .dd Address which alias expands to
+  ** .dt %t .dd Character which indicates if the alias is tagged for inclusion
   ** .de
   */
   { "allow_8bit",       DT_BOOL, R_NONE, OPT_ALLOW_8BIT, 1 },
@@ -245,27 +245,27 @@ struct Option MuttVars[] = {
   ** This variable describes the format of the ``attachment'' menu.  The
   ** following \fCprintf(3)\fP-style sequences are understood:
   ** .dl
-  ** .dt %C  .dd charset
-  ** .dt %c  .dd requires charset conversion (``n'' or ``c'')
-  ** .dt %D  .dd deleted flag
-  ** .dt %d  .dd description (if none, falls back to %F)
+  ** .dt %C  .dd Charset
+  ** .dt %c  .dd Requires charset conversion (``n'' or ``c'')
+  ** .dt %D  .dd Deleted flag
+  ** .dt %d  .dd Description (if none, falls back to %F)
   ** .dt %e  .dd MIME content-transfer-encoding
-  ** .dt %F  .dd filename in content-disposition header (if none, falls back to %f)
-  ** .dt %f  .dd filename
-  ** .dt %I  .dd disposition (``I'' for inline, ``A'' for attachment)
-  ** .dt %m  .dd major MIME type
+  ** .dt %f  .dd Filename
+  ** .dt %F  .dd Filename in content-disposition header (if none, falls back to %f)
+  ** .dt %I  .dd Disposition (``I'' for inline, ``A'' for attachment)
+  ** .dt %m  .dd Major MIME type
   ** .dt %M  .dd MIME subtype
-  ** .dt %n  .dd attachment number
+  ** .dt %n  .dd Attachment number
   ** .dt %Q  .dd ``Q'', if MIME part qualifies for attachment counting
-  ** .dt %s  .dd size
-  ** .dt %t  .dd tagged flag
-  ** .dt %T  .dd graphic tree characters
-  ** .dt %u  .dd unlink (=to delete) flag
-  ** .dt %X  .dd number of qualifying MIME parts in this part and its children
+  ** .dt %s  .dd Size
+  ** .dt %T  .dd Graphic tree characters
+  ** .dt %t  .dd Tagged flag
+  ** .dt %u  .dd Unlink (=to delete) flag
+  ** .dt %X  .dd Number of qualifying MIME parts in this part and its children
   **             (please see the ``$attachments'' section for possible speed effects)
-  ** .dt %>X .dd right justify the rest of the string and pad with character ``X''
-  ** .dt %|X .dd pad to the end of the line with character ``X''
-  ** .dt %*X .dd soft-fill with character ``X'' as pad
+  ** .dt %>X .dd Right justify the rest of the string and pad with character ``X''
+  ** .dt %|X .dd Pad to the end of the line with character ``X''
+  ** .dt %*X .dd Soft-fill with character ``X'' as pad
   ** .de
   ** .pp
   ** For an explanation of ``soft-fill'', see the $$index_format documentation.
@@ -464,9 +464,9 @@ struct Option MuttVars[] = {
   ** menu.  This string is similar to $$status_format, but has its own
   ** set of \fCprintf(3)\fP-like sequences:
   ** .dl
-  ** .dt %a .dd total number of attachments
-  ** .dt %h .dd local hostname
-  ** .dt %l .dd approximate size (in bytes) of the current message
+  ** .dt %a .dd Total number of attachments
+  ** .dt %h .dd Local hostname
+  ** .dt %l .dd Approximate size (in bytes) of the current message
   ** .dt %v .dd NeoMutt version string
   ** .de
   ** .pp
@@ -906,24 +906,23 @@ struct Option MuttVars[] = {
   ** personal taste.  This string is similar to $$index_format, but has
   ** its own set of \fCprintf(3)\fP-like sequences:
   ** .dl
-  ** .dt %C  .dd current file number
-  ** .dt %d  .dd date/time folder was last modified
-  ** .dt %D  .dd date/time folder was last modified using $$date_format.
-  ** .dt %f  .dd filename (``/'' is appended to directory names,
-  **             ``@'' to symbolic links and ``*'' to executable
-  **             files)
-  ** .dt %F  .dd file permissions
-  ** .dt %g  .dd group name (or numeric gid, if missing)
-  ** .dt %l  .dd number of hard links
-  ** .dt %m  .dd number of messages in the mailbox *
-  ** .dt %n  .dd number of unread messages in the mailbox *
-  ** .dt %N  .dd N if mailbox has new mail, blank otherwise
-  ** .dt %s  .dd size in bytes
+  ** .dt %C  .dd Current file number
+  ** .dt %d  .dd Date/time folder was last modified
+  ** .dt %D  .dd Date/time folder was last modified using $$date_format.
+  ** .dt %f  .dd Filename (``/'' is appended to directory names,
+  **             ``@'' to symbolic links and ``*'' to executable files)
+  ** .dt %F  .dd File permissions
+  ** .dt %g  .dd Group name (or numeric gid, if missing)
+  ** .dt %l  .dd Number of hard links
+  ** .dt %m  .dd Number of messages in the mailbox *
+  ** .dt %n  .dd Number of unread messages in the mailbox *
+  ** .dt %N  .dd ``N'' if mailbox has new mail, blank otherwise
+  ** .dt %s  .dd Size in bytes
   ** .dt %t  .dd ``*'' if the file is tagged, blank otherwise
-  ** .dt %u  .dd owner name (or numeric uid, if missing)
-  ** .dt %>X .dd right justify the rest of the string and pad with character ``X''
-  ** .dt %|X .dd pad to the end of the line with character ``X''
-  ** .dt %*X .dd soft-fill with character ``X'' as pad
+  ** .dt %u  .dd Owner name (or numeric uid, if missing)
+  ** .dt %>X .dd Right justify the rest of the string and pad with character ``X''
+  ** .dt %|X .dd Pad to the end of the line with character ``X''
+  ** .dt %*X .dd Soft-fill with character ``X'' as pad
   ** .de
   ** .pp
   ** For an explanation of ``soft-fill'', see the $$index_format documentation.
@@ -1103,15 +1102,15 @@ struct Option MuttVars[] = {
   ** your personal taste.  This string is similar to ``$index_format'', but
   ** has its own set of printf()-like sequences:
   ** .dl
-  ** .dt %C  .dd current newsgroup number
-  ** .dt %d  .dd description of newsgroup (becomes from server)
-  ** .dt %f  .dd newsgroup name
+  ** .dt %C  .dd Current newsgroup number
+  ** .dt %d  .dd Description of newsgroup (becomes from server)
+  ** .dt %f  .dd Newsgroup name
   ** .dt %M  .dd - if newsgroup not allowed for direct post (moderated for example)
   ** .dt %N  .dd N if newsgroup is new, u if unsubscribed, blank otherwise
-  ** .dt %n  .dd number of new articles in newsgroup
-  ** .dt %s  .dd number of unread articles in newsgroup
-  ** .dt %>X .dd right justify the rest of the string and pad with character "X"
-  ** .dt %|X .dd pad to the end of the line with character "X"
+  ** .dt %n  .dd Number of new articles in newsgroup
+  ** .dt %s  .dd Number of unread articles in newsgroup
+  ** .dt %>X .dd Right justify the rest of the string and pad with character "X"
+  ** .dt %|X .dd Pad to the end of the line with character "X"
   ** .de
   */
 #endif
@@ -1536,64 +1535,64 @@ struct Option MuttVars[] = {
   ** For an explanation of the %? construct, see the $status_format description.
   ** The following sequences are defined in NeoMutt:
   ** .dl
-  ** .dt %a .dd address of the author
-  ** .dt %A .dd reply-to address (if present; otherwise: address of author)
-  ** .dt %b .dd filename of the original message folder (think mailbox)
-  ** .dt %B .dd the list to which the letter was sent, or else the folder name (%b).
-  ** .dt %c .dd number of characters (bytes) in the message
-  ** .dt %C .dd current message number
-  ** .dt %d .dd date and time of the message in the format specified by
+  ** .dt %a .dd Address of the author
+  ** .dt %A .dd Reply-to address (if present; otherwise: address of author)
+  ** .dt %b .dd Filename of the original message folder (think mailbox)
+  ** .dt %B .dd The list to which the letter was sent, or else the folder name (%b).
+  ** .dt %c .dd Number of characters (bytes) in the message
+  ** .dt %C .dd Current message number
+  ** .dt %d .dd Date and time of the message in the format specified by
   **            $$date_format converted to sender's time zone
-  ** .dt %D .dd date and time of the message in the format specified by
+  ** .dt %D .dd Date and time of the message in the format specified by
   **            $$date_format converted to the local time zone
-  ** .dt %e .dd current message number in thread
-  ** .dt %E .dd number of messages in current thread
-  ** .dt %f .dd sender (address + real name), either From: or Return-Path:
-  ** .dt %F .dd author name, or recipient name if the message is from you
-  ** .dt %g .dd newsgroup name (if compiled with NNTP support)
-  ** .dt %g .dd message labels (e.g. notmuch tags)
-  ** .dt %H .dd spam attribute(s) of this message
-  ** .dt %I .dd initials of author
-  ** .dt %i .dd message-id of the current message
-  ** .dt %K .dd the list to which the letter was sent (if any; otherwise: empty).
-  ** .dt %l .dd number of lines in the message (does not work with maildir,
-  **            mh, and possibly IMAP folders)
+  ** .dt %e .dd Current message number in thread
+  ** .dt %E .dd Number of messages in current thread
+  ** .dt %f .dd Sender (address + real name), either From: or Return-Path:
+  ** .dt %F .dd Author name, or recipient name if the message is from you
+  ** .dt %g .dd Newsgroup name (if compiled with NNTP support)
+  ** .dt %g .dd Message labels (e.g. notmuch tags)
+  ** .dt %H .dd Spam attribute(s) of this message
+  ** .dt %I .dd Initials of author
+  ** .dt %i .dd Message-id of the current message
+  ** .dt %K .dd The list to which the letter was sent (if any; otherwise: empty)
+  ** .dt %l .dd Number of lines in the message (does not work with maildir,
+  **            Mh, and possibly IMAP folders)
   ** .dt %L .dd If an address in the ``To:'' or ``Cc:'' header field matches an address
-  **            defined by the users ``$subscribe'' command, this displays
-  **            "To <list-name>", otherwise the same as %F.
-  ** .dt %m .dd total number of message in the mailbox
-  ** .dt %M .dd number of hidden messages if the thread is collapsed.
-  ** .dt %N .dd message score
-  ** .dt %n .dd author's real name (or address if missing)
-  ** .dt %O .dd original save folder where NeoMutt would formerly have
-  **            stashed the message: list name or recipient name
-  **            if not sent to a list
-  ** .dt %P .dd progress indicator for the built-in pager (how much of the file has been displayed)
-  ** .dt %q .dd newsgroup name (if compiled with NNTP support)
-  ** .dt %r .dd comma separated list of ``To:'' recipients
-  ** .dt %R .dd comma separated list of ``Cc:'' recipients
-  ** .dt %s .dd subject of the message
-  ** .dt %S .dd single character status of the message (``N''/``O''/``D''/``d''/``!''/``r''/``\(as'')
+  **            Defined by the users ``$subscribe'' command, this displays
+  **            "To <list-name>", otherwise the same as %F
+  ** .dt %m .dd Total number of message in the mailbox
+  ** .dt %M .dd Number of hidden messages if the thread is collapsed
+  ** .dt %N .dd Message score
+  ** .dt %n .dd Author's real name (or address if missing)
+  ** .dt %O .dd Original save folder where NeoMutt would formerly have
+  **            Stashed the message: list name or recipient name
+  **            If not sent to a list
+  ** .dt %P .dd Progress indicator for the built-in pager (how much of the file has been displayed)
+  ** .dt %q .dd Newsgroup name (if compiled with NNTP support)
+  ** .dt %r .dd Comma separated list of ``To:'' recipients
+  ** .dt %R .dd Comma separated list of ``Cc:'' recipients
+  ** .dt %s .dd Subject of the message
+  ** .dt %S .dd Single character status of the message (``N''/``O''/``D''/``d''/``!''/``r''/``\(as'')
   ** .dt %t .dd ``To:'' field (recipients)
-  ** .dt %T .dd the appropriate character from the $$to_chars string
-  ** .dt %u .dd user (login) name of the author
-  ** .dt %v .dd first name of the author, or the recipient if the message is from you
-  ** .dt %W .dd name of organization of author (``Organization:'' field)
+  ** .dt %T .dd The appropriate character from the $$to_chars string
+  ** .dt %u .dd User (login) name of the author
+  ** .dt %v .dd First name of the author, or the recipient if the message is from you
+  ** .dt %W .dd Name of organization of author (``Organization:'' field)
   ** .dt %x .dd ``X-Comment-To:'' field (if present and compiled with NNTP support)
-  ** .dt %X .dd number of attachments
+  ** .dt %X .dd Number of attachments
   **            (please see the ``$attachments'' section for possible speed effects)
   ** .dt %y .dd ``X-Label:'' field, if present
   ** .dt %Y .dd ``X-Label:'' field, if present, and \fI(1)\fP not at part of a thread tree,
   **            \fI(2)\fP at the top of a thread, or \fI(3)\fP ``X-Label:'' is different from
-  **            preceding message's ``X-Label:''.
-  ** .dt %Z .dd a three character set of message status flags.
-  **            the first character is new/read/replied flags (``n''/``o''/``r''/``O''/``N'').
-  **            the second is deleted or encryption flags (``D''/``d''/``S''/``P''/``s''/``K'').
-  **            the third is either tagged/flagged (``\(as''/``!''), or one of the characters
-  **            listed in $$to_chars.
-  ** .dt %zs .dd message status flags
-  ** .dt %zc .dd message crypto flags
-  ** .dt %zt .dd message tag flags
+  **            Preceding message's ``X-Label:''
+  ** .dt %Z .dd A three character set of message status flags.
+  **            The first character is new/read/replied flags (``n''/``o''/``r''/``O''/``N'').
+  **            The second is deleted or encryption flags (``D''/``d''/``S''/``P''/``s''/``K'').
+  **            The third is either tagged/flagged (``\(as''/``!''), or one of the characters
+  **            Listed in $$to_chars.
+  ** .dt %zs .dd Message status flags
+  ** .dt %zc .dd Message crypto flags
+  ** .dt %zt .dd Message tag flags
   ** .dt %{fmt} .dd the date and time of the message is converted to sender's
   **                time zone, and ``fmt'' is expanded by the library function
   **                \fCstrftime(3)\fP; a leading bang disables locales
@@ -1949,10 +1948,10 @@ struct Option MuttVars[] = {
   ** chain selection screen.  The following \fCprintf(3)\fP-like sequences are
   ** supported:
   ** .dl
-  ** .dt %n .dd The running number on the menu.
-  ** .dt %c .dd Remailer capabilities.
-  ** .dt %s .dd The remailer's short name.
-  ** .dt %a .dd The remailer's e-mail address.
+  ** .dt %a .dd The remailer's e-mail address
+  ** .dt %c .dd Remailer capabilities
+  ** .dt %n .dd The running number on the menu
+  ** .dt %s .dd The remailer's short name
   ** .de
   */
   { "mixmaster",        DT_PATH, R_NONE, UL &Mixmaster, UL MIXMASTER },
@@ -2025,12 +2024,12 @@ struct Option MuttVars[] = {
   ** indexes of read articles.  The following printf-style sequence
   ** is understood:
   ** .dl
-  ** .dt %a .dd account url
-  ** .dt %p .dd port
-  ** .dt %P .dd port if specified
-  ** .dt %s .dd news server name
-  ** .dt %S .dd url schema
-  ** .dt %u .dd username
+  ** .dt %a .dd Account url
+  ** .dt %p .dd Port
+  ** .dt %P .dd Port if specified
+  ** .dt %s .dd News server name
+  ** .dt %S .dd Url schema
+  ** .dt %u .dd Username
   ** .de
   */
   { "nntp_authenticators", DT_STRING, R_NONE, UL &NntpAuthenticators, UL 0 },
@@ -2344,16 +2343,16 @@ struct Option MuttVars[] = {
   ** your personal taste. This string is similar to $$index_format, but
   ** has its own set of \fCprintf(3)\fP-like sequences:
   ** .dl
-  ** .dt %n     .dd number
-  ** .dt %k     .dd key id
-  ** .dt %u     .dd user id
-  ** .dt %a     .dd algorithm
-  ** .dt %l     .dd key length
-  ** .dt %p     .dd protocol
-  ** .dt %f     .dd flags
-  ** .dt %c     .dd capabilities
-  ** .dt %t     .dd trust/validity of the key-uid association
-  ** .dt %[<s>] .dd date of the key where <s> is an \fCstrftime(3)\fP expression
+  ** .dt %a     .dd Algorithm
+  ** .dt %c     .dd Capabilities
+  ** .dt %f     .dd Flags
+  ** .dt %k     .dd Key id
+  ** .dt %l     .dd Key length
+  ** .dt %n     .dd Number
+  ** .dt %p     .dd Protocol
+  ** .dt %t     .dd Trust/validity of the key-uid association
+  ** .dt %u     .dd User id
+  ** .dt %[<s>] .dd Date of the key where <s> is an \fCstrftime(3)\fP expression
   ** .de
   ** .pp
   ** (PGP only)
@@ -2840,14 +2839,14 @@ struct Option MuttVars[] = {
   ** This variable describes the format of the ``query'' menu. The
   ** following \fCprintf(3)\fP-style sequences are understood:
   ** .dl
-  ** .dt %a  .dd destination address
-  ** .dt %c  .dd current entry number
-  ** .dt %e  .dd extra information *
-  ** .dt %n  .dd destination name
+  ** .dt %a  .dd Destination address
+  ** .dt %c  .dd Current entry number
+  ** .dt %e  .dd Extra information *
+  ** .dt %n  .dd Destination name
   ** .dt %t  .dd ``*'' if current entry is tagged, a space otherwise
-  ** .dt %>X .dd right justify the rest of the string and pad with ``X''
-  ** .dt %|X .dd pad to the end of the line with ``X''
-  ** .dt %*X .dd soft-fill with character ``X'' as pad
+  ** .dt %>X .dd Right justify the rest of the string and pad with ``X''
+  ** .dt %|X .dd Pad to the end of the line with ``X''
+  ** .dt %*X .dd Soft-fill with character ``X'' as pad
   ** .de
   ** .pp
   ** For an explanation of ``soft-fill'', see the $$index_format documentation.
@@ -3980,32 +3979,32 @@ struct Option MuttVars[] = {
   ** menu.  This string is similar to $$index_format, but has its own
   ** set of \fCprintf(3)\fP-like sequences:
   ** .dl
-  ** .dt %b  .dd number of mailboxes with new mail *
-  ** .dt %d  .dd number of deleted messages *
-  ** .dt %f  .dd the full pathname of the current mailbox
-  ** .dt %F  .dd number of flagged messages *
-  ** .dt %h  .dd local hostname
-  ** .dt %l  .dd size (in bytes) of the current mailbox *
-  ** .dt %L  .dd size (in bytes) of the messages shown
+  ** .dt %b  .dd Number of mailboxes with new mail *
+  ** .dt %d  .dd Number of deleted messages *
+  ** .dt %f  .dd The full pathname of the current mailbox
+  ** .dt %F  .dd Number of flagged messages *
+  ** .dt %h  .dd Local hostname
+  ** .dt %l  .dd Size (in bytes) of the current mailbox *
+  ** .dt %L  .dd Size (in bytes) of the messages shown
   **             (i.e., which match the current limit) *
-  ** .dt %m  .dd the number of messages in the mailbox *
-  ** .dt %M  .dd the number of messages shown (i.e., which match the current limit) *
-  ** .dt %n  .dd number of new messages in the mailbox *
-  ** .dt %o  .dd number of old unread messages *
-  ** .dt %p  .dd number of postponed messages *
-  ** .dt %P  .dd percentage of the way through the index
-  ** .dt %r  .dd modified/read-only/won't-write/attach-message indicator,
-  **             according to $$status_chars
-  ** .dt %R  .dd number of read messages *
-  ** .dt %s  .dd current sorting mode ($$sort)
-  ** .dt %S  .dd current aux sorting method ($$sort_aux)
-  ** .dt %t  .dd number of tagged messages *
-  ** .dt %u  .dd number of unread messages *
+  ** .dt %m  .dd The number of messages in the mailbox *
+  ** .dt %M  .dd The number of messages shown (i.e., which match the current limit) *
+  ** .dt %n  .dd Number of new messages in the mailbox *
+  ** .dt %o  .dd Number of old unread messages *
+  ** .dt %p  .dd Number of postponed messages *
+  ** .dt %P  .dd Percentage of the way through the index
+  ** .dt %r  .dd Modified/read-only/won't-write/attach-message indicator,
+  **             According to $$status_chars
+  ** .dt %R  .dd Number of read messages *
+  ** .dt %s  .dd Current sorting mode ($$sort)
+  ** .dt %S  .dd Current aux sorting method ($$sort_aux)
+  ** .dt %t  .dd Number of tagged messages *
+  ** .dt %u  .dd Number of unread messages *
   ** .dt %v  .dd NeoMutt version string
-  ** .dt %V  .dd currently active limit pattern, if any *
-  ** .dt %>X .dd right justify the rest of the string and pad with ``X''
-  ** .dt %|X .dd pad to the end of the line with ``X''
-  ** .dt %*X .dd soft-fill with character ``X'' as pad
+  ** .dt %V  .dd Currently active limit pattern, if any *
+  ** .dt %>X .dd Right justify the rest of the string and pad with ``X''
+  ** .dt %|X .dd Pad to the end of the line with ``X''
+  ** .dt %*X .dd Soft-fill with character ``X'' as pad
   ** .de
   ** .pp
   ** For an explanation of ``soft-fill'', see the $$index_format documentation.

diff --git a/muttlib.c b/muttlib.c
index 1b01f0a63c6dc3e6a86ac59e4dd9a34582757458..447aff7c96b8231fb474587ffa6e0091d92e7574 100644 (file)
--- a/muttlib.c
+++ b/muttlib.c
@@ -882,14 +882,14 @@ char *mutt_apply_replace(char *dbuf, size_t dlen, char *sbuf, struct ReplaceList
 
 /**
  * mutt_expando_format - Expand expandos (%x) in a string
- * @param dest     output buffer
- * @param destlen  output buffer len
- * @param col      starting column (nonzero when called recursively)
- * @param cols     maximum columns
- * @param src      template string
- * @param callback callback for processing
- * @param data     callback data
- * @param flags    callback flags
+ * @param[out] buf      Buffer in which to save string
+ * @param[in]  buflen   Buffer length
+ * @param[in]  col      Starting column
+ * @param[in]  cols     Number of screen columns
+ * @param[in]  src      Printf-like format string
+ * @param[in]  callback Callback for processing
+ * @param[in]  data     Callback data
+ * @param[in]  flags    Callback flags
  */
 void mutt_expando_format(char *buf, size_t buflen, size_t col, int cols, const char *src,
                          format_t *callback, unsigned long data, enum FormatFlag flags)

diff --git a/ncrypt/crypt_gpgme.c b/ncrypt/crypt_gpgme.c
index f40a95b4f22b21036edf4f4c8e2ba4263020efb7..c4492c598c87208992dc981f8de880eca04d013a 100644 (file)
--- a/ncrypt/crypt_gpgme.c
+++ b/ncrypt/crypt_gpgme.c
@@ -2891,25 +2891,41 @@ int smime_gpgme_application_handler(struct Body *a, struct State *s)
 }
 
 /**
- * crypt_format_str - Format an entry on the CRYPT key selection menu
+ * crypt_format_str - Format a string for the key selection menu
+ * @param[out] buf      Buffer in which to save string
+ * @param[in]  buflen   Buffer length
+ * @param[in]  col      Starting column
+ * @param[in]  cols     Number of screen columns
+ * @param[in]  op       printf-like operator, e.g. 't'
+ * @param[in]  src      printf-like format string
+ * @param[in]  prec     Field precision, e.g. "-3.4"
+ * @param[in]  if_str   If condition is met, display this string
+ * @param[in]  else_str Otherwise, display this string
+ * @param[in]  data     Pointer to the mailbox Context
+ * @param[in]  flags    Format flags
+ * @retval src (unchanged)
  *
- * * \%u user id
- * * \%n number
- * * \%t trust/validity of the key-uid association
- * * \%p         protocol
- * * \%[...] date of key using strftime(3)
+ * crypt_format_str() is a callback function for mutt_expando_format().
  *
- * * \%k key id
- * * \%a algorithm
- * * \%l length
- * * \%f flags
- * * \%c capabilities
- *
- * * \%K key id of the principal key
- * * \%A algorithm of the principal key
- * * \%L length of the principal key
- * * \%F flags of the principal key
- * * \%C capabilities of the principal key
+ * | Expando | Description
+ * |:--------|:--------------------------------------------------------
+ * | \%u     | User id
+ * | \%n     | Number
+ * | \%t     | Trust/validity of the key-uid association
+ * | \%p     | Protocol
+ * | \%[...] | Date of key using strftime(3)
+ * |         |
+ * | \%k     | Key id
+ * | \%a     | Algorithm
+ * | \%l     | Length
+ * | \%f     | Flags
+ * | \%c     | Capabilities
+ * |         |
+ * | \%K     | Key id of the principal key
+ * | \%A     | Algorithm of the principal key
+ * | \%L     | Length of the principal key
+ * | \%F     | Flags of the principal key
+ * | \%C     | Capabilities of the principal key
  */
 static const char *crypt_format_str(char *buf, size_t buflen, size_t col, int cols,
                                     char op, const char *src, const char *prec,
@@ -3110,7 +3126,11 @@ static const char *crypt_format_str(char *buf, size_t buflen, size_t col, int co
 }
 
 /**
- * crypt_entry - Used by the display function to format a line
+ * crypt_entry - Format a menu item for the key selection list
+ * @param[out] buf    Buffer in which to save string
+ * @param[in]  buflen Buffer length
+ * @param[in]  menu   Menu containing aliases
+ * @param[in]  num    Index into the menu
  */
 static void crypt_entry(char *buf, size_t buflen, struct Menu *menu, int num)
 {

diff --git a/ncrypt/pgpkey.c b/ncrypt/pgpkey.c
index cf1a06fcde40e9f806fda97e34ed4200b8b0148b..d141559ba2a1d4736d1408fc6d285b62d4c3a015 100644 (file)
--- a/ncrypt/pgpkey.c
+++ b/ncrypt/pgpkey.c
@@ -295,6 +295,13 @@ static const char *pgp_entry_fmt(char *buf, size_t buflen, size_t col, int cols,
   return src;
 }
 
+/**
+ * pgp_entry - Format a menu item for the pgp key list
+ * @param[out] buf    Buffer in which to save string
+ * @param[in]  buflen Buffer length
+ * @param[in]  menu   Menu containing aliases
+ * @param[in]  num    Index into the menu
+ */
 static void pgp_entry(char *buf, size_t buflen, struct Menu *menu, int num)
 {
   struct PgpUid **KeyTable = (struct PgpUid **) menu->data;

diff --git a/ncrypt/smime.c b/ncrypt/smime.c
index aa3934e419d98e10cc6c0b27a7e0afccebbb5959..99dc61198ee29337ceaf749d491f634203260a34 100644 (file)
--- a/ncrypt/smime.c
+++ b/ncrypt/smime.c
@@ -351,6 +351,13 @@ static char *smime_key_flags(int flags)
   return buf;
 }
 
+/**
+ * smime_entry - Format a menu item for the smime key list
+ * @param[out] buf    Buffer in which to save string
+ * @param[in]  buflen Buffer length
+ * @param[in]  menu   Menu containing aliases
+ * @param[in]  num    Index into the menu
+ */
 static void smime_entry(char *buf, size_t buflen, struct Menu *menu, int num)
 {
   struct SmimeKey **Table = (struct SmimeKey **) menu->data;

diff --git a/newsrc.c b/newsrc.c
index 7d1c569062a46c915c38b3b0ddbc45d83e18b827..e2768fdb89ef67e0dc8ecba1896bb6f81531a8b5 100644 (file)
--- a/newsrc.c
+++ b/newsrc.c
@@ -858,14 +858,30 @@ void nntp_clear_cache(struct NntpServer *nserv)
 }
 
 /**
- * nntp_format_str - Format a string, like printf()
+ * nntp_format_str - Expand the newsrc filename
+ * @param[out] buf      Buffer in which to save string
+ * @param[in]  buflen   Buffer length
+ * @param[in]  col      Starting column
+ * @param[in]  cols     Number of screen columns
+ * @param[in]  op       printf-like operator, e.g. 't'
+ * @param[in]  src      printf-like format string
+ * @param[in]  prec     Field precision, e.g. "-3.4"
+ * @param[in]  if_str   If condition is met, display this string
+ * @param[in]  else_str Otherwise, display this string
+ * @param[in]  data     Pointer to the mailbox Context
+ * @param[in]  flags    Format flags
+ * @retval src (unchanged)
  *
- * %a = account url
- * %p = port
- * %P = port if specified
- * %s = news server name
- * %S = url schema
- * %u = username
+ * nntp_format_str() is a callback function for mutt_expando_format().
+ *
+ * | Expando | Description
+ * |:--------|:--------------------------------------------------------
+ * | \%a     | Account url
+ * | \%p     | Port
+ * | \%P     | Port if specified
+ * | \%s     | News server name
+ * | \%S     | Url schema
+ * | \%u     | Username
  */
 const char *nntp_format_str(char *buf, size_t buflen, size_t col, int cols, char op,
                             const char *src, const char *prec, const char *if_str,

diff --git a/postpone.c b/postpone.c
index 8e95cbe9bae2e42a2e6c05070f6268aec034feab..6035fca3c905ffe159393b4b8fdb9d5c984c1c27 100644 (file)
--- a/postpone.c
+++ b/postpone.c
@@ -172,6 +172,13 @@ void mutt_update_num_postponed(void)
   UpdateNumPostponed = 1;
 }
 
+/**
+ * post_entry - Format a menu item for the email list
+ * @param[out] buf    Buffer in which to save string
+ * @param[in]  buflen Buffer length
+ * @param[in]  menu   Menu containing aliases
+ * @param[in]  num    Index into the menu
+ */
 static void post_entry(char *buf, size_t buflen, struct Menu *menu, int num)
 {
   struct Context *ctx = (struct Context *) menu->data;

diff --git a/query.c b/query.c
index 011cc70c68fcd5ee1fccd775fd9d14d5077cd457..0933d6d1ed21865f37b82bb62197b092f11bd7a6 100644 (file)
--- a/query.c
+++ b/query.c
@@ -206,6 +206,31 @@ static int query_search(struct Menu *m, regex_t *re, int n)
   return REG_NOMATCH;
 }
 
+/**
+ * query_format_str - Format a string for the query menu
+ * @param[out] buf      Buffer in which to save string
+ * @param[in]  buflen   Buffer length
+ * @param[in]  col      Starting column
+ * @param[in]  cols     Number of screen columns
+ * @param[in]  op       printf-like operator, e.g. 't'
+ * @param[in]  src      printf-like format string
+ * @param[in]  prec     Field precision, e.g. "-3.4"
+ * @param[in]  if_str   If condition is met, display this string
+ * @param[in]  else_str Otherwise, display this string
+ * @param[in]  data     Pointer to the mailbox Context
+ * @param[in]  flags    Format flags
+ * @retval src (unchanged)
+ *
+ * query_format_str() is a callback function for mutt_expando_format().
+ *
+ * | Expando | Description
+ * |:--------|:--------------------------------------------------------
+ * | \%a     | Destination address
+ * | \%c     | Current entry number
+ * | \%e     | Extra information
+ * | \%n     | Destination name
+ * | \%t     | '*' if current entry is tagged, a space otherwise
+ */
 static const char *query_format_str(char *buf, size_t buflen, size_t col, int cols,
                                     char op, const char *src, const char *prec,
                                     const char *if_str, const char *else_str,
@@ -259,6 +284,13 @@ static const char *query_format_str(char *buf, size_t buflen, size_t col, int co
   return src;
 }
 
+/**
+ * query_entry - Format a menu item for the query list
+ * @param[out] buf    Buffer in which to save string
+ * @param[in]  buflen Buffer length
+ * @param[in]  menu   Menu containing aliases
+ * @param[in]  num    Index into the menu
+ */
 static void query_entry(char *buf, size_t buflen, struct Menu *menu, int num)
 {
   struct Entry *entry = &((struct Entry *) menu->data)[num];

diff --git a/recvattach.c b/recvattach.c
index 4c940426919a1f7a13cb1970e2f76ee29ef075b6..8437953bf7b52708ca9d803009f866829ad424fe 100644 (file)
--- a/recvattach.c
+++ b/recvattach.c
@@ -140,25 +140,41 @@ void mutt_update_tree(struct AttachCtx *actx)
 }
 
 /**
- * attach_format_str - Format string for attachment menu
+ * attach_format_str - Format a string for the attachment menu
+ * @param[out] buf      Buffer in which to save string
+ * @param[in]  buflen   Buffer length
+ * @param[in]  col      Starting column
+ * @param[in]  cols     Number of screen columns
+ * @param[in]  op       printf-like operator, e.g. 't'
+ * @param[in]  src      printf-like format string
+ * @param[in]  prec     Field precision, e.g. "-3.4"
+ * @param[in]  if_str   If condition is met, display this string
+ * @param[in]  else_str Otherwise, display this string
+ * @param[in]  data     Pointer to the mailbox Context
+ * @param[in]  flags    Format flags
+ * @retval src (unchanged)
+ *
+ * attach_format_str() is a callback function for mutt_expando_format().
  *
  * | Expando | Description
  * |:--------|:--------------------------------------------------------
- * | \%c     | character set: convert?
- * | \%C     | character set
- * | \%D     | deleted flag
- * | \%d     | description
+ * | \%C     | Character set
+ * | \%c     | Character set: convert?
+ * | \%D     | Deleted flag
+ * | \%d     | Description
  * | \%e     | MIME content-transfer-encoding
- * | \%F     | filename for content-disposition header
- * | \%f     | filename
- * | \%I     | content-disposition, either I (inline) or A (attachment)
- * | \%t     | tagged flag
- * | \%T     | tree chars
- * | \%m     | major MIME type
+ * | \%f     | Filename
+ * | \%F     | Filename for content-disposition header
+ * | \%I     | Content-disposition, either I (inline) or A (attachment)
+ * | \%m     | Major MIME type
  * | \%M     | MIME subtype
- * | \%n     | attachment number
- * | \%s     | size
- * | \%u     | unlink
+ * | \%n     | Attachment number
+ * | \%Q     | 'Q', if MIME part qualifies for attachment counting
+ * | \%s     | Size
+ * | \%t     | Tagged flag
+ * | \%T     | Tree chars
+ * | \%u     | Unlink
+ * | \%X     | Number of qualifying MIME parts in this part and its children
  */
 const char *attach_format_str(char *buf, size_t buflen, size_t col, int cols,
                               char op, const char *src, const char *prec,
@@ -377,6 +393,13 @@ const char *attach_format_str(char *buf, size_t buflen, size_t col, int cols,
   return src;
 }
 
+/**
+ * attach_entry - Format a menu item for the attachment list
+ * @param[out] buf    Buffer in which to save string
+ * @param[in]  buflen Buffer length
+ * @param[in]  menu   Menu containing aliases
+ * @param[in]  num    Index into the menu
+ */
 static void attach_entry(char *buf, size_t buflen, struct Menu *menu, int num)
 {
   struct AttachCtx *actx = (struct AttachCtx *) menu->data;

diff --git a/remailer.c b/remailer.c
index 2781d00a656fee08f2a12a5b44fe5c839d13705f..f4a648fb4a9e50268e863ea62993deb3c8d7b759 100644 (file)
--- a/remailer.c
+++ b/remailer.c
@@ -350,12 +350,28 @@ static const char *mix_format_caps(struct Remailer *r)
 }
 
 /**
- * mix_format_str - Format an entry for the remailer menu
+ * mix_format_str - Format a string for the remailer menu
+ * @param[out] buf      Buffer in which to save string
+ * @param[in]  buflen   Buffer length
+ * @param[in]  col      Starting column
+ * @param[in]  cols     Number of screen columns
+ * @param[in]  op       printf-like operator, e.g. 't'
+ * @param[in]  src      printf-like format string
+ * @param[in]  prec     Field precision, e.g. "-3.4"
+ * @param[in]  if_str   If condition is met, display this string
+ * @param[in]  else_str Otherwise, display this string
+ * @param[in]  data     Pointer to the mailbox Context
+ * @param[in]  flags    Format flags
+ * @retval src (unchanged)
  *
- * * %n number
- * * %c capabilities
- * * %s short name
- * * %a address
+ * mix_format_str() is a callback function for mutt_expando_format().
+ *
+ * | Expando | Description
+ * |:--------|:--------------------------------------------------------
+ * | \%a     | The remailer's e-mail address
+ * | \%c     | Remailer capabilities
+ * | \%n     | The running number on the menu
+ * | \%s     | The remailer's short name
  */
 static const char *mix_format_str(char *buf, size_t buflen, size_t col, int cols,
                                   char op, const char *src, const char *prec,
@@ -412,6 +428,13 @@ static const char *mix_format_str(char *buf, size_t buflen, size_t col, int cols
   return src;
 }
 
+/**
+ * mix_entry - Format a menu item for the mixmaster chain list
+ * @param[out] buf    Buffer in which to save string
+ * @param[in]  buflen Buffer length
+ * @param[in]  menu   Menu containing aliases
+ * @param[in]  num    Index into the menu
+ */
 static void mix_entry(char *buf, size_t buflen, struct Menu *menu, int num)
 {
   struct Remailer **type2_list = (struct Remailer **) menu->data;

diff --git a/sidebar.c b/sidebar.c
index 4d4b9646d8f823f1cad4703d561a2420043c8345..ad16cae2f5b80be0d9fdcd1b5aaaa51bf13a198c 100644 (file)
--- a/sidebar.c
+++ b/sidebar.c
@@ -88,25 +88,33 @@ enum SidebarSrc
 } sidebar_source = SB_SRC_INCOMING;
 
 /**
- * sidebar_format_str - Create the string to show in the sidebar
- * @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]  if_str    If condition is met, display this string
- * @param[in]  else_str  Otherwise, display this string
- * @param[in]  data        Pointer to our sidebar_entry
- * @param[in]  flags       Format flags, e.g. MUTT_FORMAT_OPTIONAL
+ * sidebar_format_str - Format a string for the sidebar
+ * @param[out] buf      Buffer in which to save string
+ * @param[in]  buflen   Buffer length
+ * @param[in]  col      Starting column
+ * @param[in]  cols     Number of screen columns
+ * @param[in]  op       printf-like operator, e.g. 't'
+ * @param[in]  src      printf-like format string
+ * @param[in]  prec     Field precision, e.g. "-3.4"
+ * @param[in]  if_str   If condition is met, display this string
+ * @param[in]  else_str Otherwise, display this string
+ * @param[in]  data     Pointer to the mailbox Context
+ * @param[in]  flags    Format flags
  * @retval src (unchanged)
  *
- * sidebar_format_str is a callback function for mutt_expando_format.  It understands
- * six operators. '%B' : Mailbox name, '%F' : Number of flagged messages,
- * '%N' : Number of new messages, '%S' : Size (total number of messages),
- * '%!' : Icon denoting number of flagged messages.
- * '%n' : N if folder has new mail, blank otherwise.
+ * sidebar_format_str() is a callback function for mutt_expando_format().
+ *
+ * | Expando | Description
+ * |:--------|:--------------------------------------------------------
+ * | \%B     | Name of the mailbox
+ * | \%d     | Number of deleted messages
+ * | \%F     | Number of Flagged messages in the mailbox
+ * | \%L     | Number of messages after limiting
+ * | \%n     | N if mailbox has new mail, blank otherwise
+ * | \%N     | Number of unread messages in the mailbox
+ * | \%S     | Size of mailbox (total number of messages)
+ * | \%t     | Number of tagged messages
+ * | \%!     | 'n!' Flagged messages
  */
 static const char *sidebar_format_str(char *buf, size_t buflen, size_t col, int cols,
                                       char op, const char *src, const char *prec,

diff --git a/status.c b/status.c
index f1a0636587b480c757d19063bf3cdab7f2d05ec0..6721cce26dcf7f6d401166fe9a2802de0f77aed9 100644 (file)
--- a/status.c
+++ b/status.c
@@ -47,31 +47,47 @@ static char *get_sort_str(char *buf, size_t buflen, int method)
 
 static void status_line(char *buf, size_t buflen, size_t col, int cols,
                         struct Menu *menu, const char *p);
+
 /**
- * status_format_str - Format a string for the status bar
+ * status_format_str - Create the status bar string
+ * @param[out] buf      Buffer in which to save string
+ * @param[in]  buflen   Buffer length
+ * @param[in]  col      Starting column
+ * @param[in]  cols     Number of screen columns
+ * @param[in]  op       printf-like operator, e.g. 't'
+ * @param[in]  src      printf-like format string
+ * @param[in]  prec     Field precision, e.g. "-3.4"
+ * @param[in]  if_str   If condition is met, display this string
+ * @param[in]  else_str Otherwise, display this string
+ * @param[in]  data     Pointer to the mailbox Context
+ * @param[in]  flags    Format flags
+ * @retval src (unchanged)
+ *
+ * status_format_str() is a callback function for mutt_expando_format().
  *
  * | Expando | Description
- * |:--------|:----------------------------------------------------------------
- * | \%b     | number of incoming folders with unread messages [option]
- * | \%d     | number of deleted messages [option]
- * | \%f     | full mailbox path
- * | \%F     | number of flagged messages [option]
- * | \%h     | hostname
- * | \%l     | length of mailbox (in bytes) [option]
- * | \%m     | total number of messages [option]
- * | \%M     | number of messages shown (virtual message count when limiting) [option]
- * | \%n     | number of new messages [option]
- * | \%o     | number of old unread messages [option]
- * | \%p     | number of postponed messages [option]
- * | \%P     | percent of way through index
- * | \%r     | readonly/wontwrite/changed flag
- * | \%R     | number of read messages [option]
- * | \%s     | current sorting method ($sort)
- * | \%S     | current aux sorting method ($sort_aux)
- * | \%t     | # of tagged messages [option]
- * | \%u     | number of unread messages [option]
+ * |:--------|:--------------------------------------------------------
+ * | \%b     | Number of incoming folders with unread messages
+ * | \%d     | Number of deleted messages
+ * | \%f     | Full mailbox path
+ * | \%F     | Number of flagged messages
+ * | \%h     | Hostname
+ * | \%l     | Length of mailbox (in bytes)
+ * | \%L     | Size (in bytes) of the messages shown
+ * | \%M     | Number of messages shown (virtual message count when limiting)
+ * | \%m     | Total number of messages
+ * | \%n     | Number of new messages
+ * | \%o     | Number of old unread messages
+ * | \%p     | Number of postponed messages
+ * | \%P     | Percent of way through index
+ * | \%R     | Number of read messages
+ * | \%r     | Readonly/wontwrite/changed flag
+ * | \%S     | Current aux sorting method ($sort_aux)
+ * | \%s     | Current sorting method ($sort)
+ * | \%t     | # of tagged messages
+ * | \%u     | Number of unread messages
+ * | \%V     | Currently active limit pattern
  * | \%v     | NeoMutt version
- * | \%V     | currently active limit pattern [option]
  */
 static const char *status_format_str(char *buf, size_t buflen, size_t col, int cols,
                                      char op, const char *src, const char *prec,