From: Richard Russon <rich@flatcap.org>
Date: Sat, 4 Aug 2018 22:07:56 +0000 (+0100)
Subject: doxy: expandos
X-Git-Tag: 2019-10-25~712^2~6
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=00fc23650134c0035d3cde035267250cffc19a09;p=neomutt

doxy: expandos
---

diff --git a/addrbook.c b/addrbook.c
index 78a54f388..215e18982 100644
--- a/addrbook.c
+++ b/addrbook.c
@@ -58,21 +58,7 @@ static const struct Mapping AliasHelp[] = {
 };
 
 /**
- * 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().
+ * alias_format_str - Format a string for the alias list - Implements ::format_t
  *
  * | Expando | Description
  * |:--------|:--------------------------------------------------------
diff --git a/browser.c b/browser.c
index a424f5d3b..741422827 100644
--- a/browser.c
+++ b/browser.c
@@ -339,21 +339,7 @@ static bool link_is_dir(const char *folder, const char *path)
 }
 
 /**
- * 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().
+ * folder_format_str - Format a string for the folder browser - Implements ::format_t
  *
  * | Expando | Description
  * |:--------|:--------------------------------------------------------
@@ -596,21 +582,7 @@ 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().
+ * group_index_format_str - Format a string for the newsgroup menu - Implements ::format_t
  *
  * | Expando | Description
  * |:--------|:--------------------------------------------------------
diff --git a/compose.c b/compose.c
index 07f12345a..4853ea573 100644
--- a/compose.c
+++ b/compose.c
@@ -795,21 +795,7 @@ static unsigned long cum_attachs_size(struct Menu *menu)
 }
 
 /**
- * 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)
- *
- * compose_format_str() is a callback function for mutt_expando_format().
+ * compose_format_str - Create the status bar string for compose mode - Implements ::format_t
  *
  * | Expando | Description
  * |:--------|:--------------------------------------------------------
diff --git a/compress.c b/compress.c
index b78c00646..f956d07c7 100644
--- a/compress.c
+++ b/compress.c
@@ -336,21 +336,7 @@ static char *escape_path(char *src)
 }
 
 /**
- * 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().
+ * compress_format_str - Expand the filenames in a command string - Implements ::format_t
  *
  * | Expando | Description
  * |:--------|:--------------------------------------------------------
diff --git a/format_flags.h b/format_flags.h
index e19e62d05..dee94f5da 100644
--- a/format_flags.h
+++ b/format_flags.h
@@ -40,6 +40,27 @@ enum FormatFlag
   MUTT_FORMAT_NOFILTER    = (1 << 7)  /**< do not allow filtering on this pass */
 };
 
+/**
+ * format_t - Prototype for a mutt_expando_format() callback function
+ * @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)
+ *
+ * Each callback function implements some expandos, e.g.
+ *
+ * | Expando | Description
+ * |:--------|:-----------
+ * | \%t     | Title
+ */
 typedef const char *format_t(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,
diff --git a/hdrline.c b/hdrline.c
index 976cfc520..9f5e5cd5a 100644
--- a/hdrline.c
+++ b/hdrline.c
@@ -464,21 +464,7 @@ static bool thread_is_old(struct Context *ctx, struct Header *hdr)
 }
 
 /**
- * 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().
+ * index_format_str - Format a string for the index list - Implements ::format_t
  *
  * | Expando | Description
  * |:--------|:-----------------------------------------------------------------
diff --git a/mutt_history.c b/mutt_history.c
index 4db61ba71..8b1d97206 100644
--- a/mutt_history.c
+++ b/mutt_history.c
@@ -41,21 +41,7 @@ static const struct Mapping HistoryHelp[] = {
 };
 
 /**
- * history_format_str - Format a string for the history 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)
- *
- * history_format_str() is a callback function for mutt_expando_format().
+ * history_format_str - Format a string for the history list - Implements ::format_t
  *
  * | Expando | Description
  * |:--------|:--------------
diff --git a/muttlib.c b/muttlib.c
index 793cdbc23..684af9aaf 100644
--- a/muttlib.c
+++ b/muttlib.c
@@ -828,7 +828,7 @@ void mutt_safe_path(char *buf, size_t buflen, struct Address *a)
  * @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]  callback Callback - Implements ::format_t
  * @param[in]  data     Callback data
  * @param[in]  flags    Callback flags
  */
diff --git a/ncrypt/crypt_gpgme.c b/ncrypt/crypt_gpgme.c
index d0348d1f7..5ad399902 100644
--- a/ncrypt/crypt_gpgme.c
+++ b/ncrypt/crypt_gpgme.c
@@ -2920,21 +2920,7 @@ int smime_gpgme_application_handler(struct Body *a, struct State *s)
 }
 
 /**
- * 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)
- *
- * crypt_format_str() is a callback function for mutt_expando_format().
+ * crypt_format_str - Format a string for the key selection menu - Implements ::format_t
  *
  * | Expando | Description
  * |:--------|:--------------------------------------------------------
diff --git a/ncrypt/pgpinvoke.c b/ncrypt/pgpinvoke.c
index 372f6cd42..d9980eea2 100644
--- a/ncrypt/pgpinvoke.c
+++ b/ncrypt/pgpinvoke.c
@@ -79,21 +79,7 @@ struct PgpCommandContext
 };
 
 /**
- * fmt_pgp_command - Format a PGP 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)
- *
- * fmt_pgp_command() is a callback function for mutt_expando_format().
+ * fmt_pgp_command - Format a PGP command string - Implements ::format_t
  *
  * | Expando | Description
  * |:--------|:-----------------------------------------------------------------
diff --git a/ncrypt/pgpkey.c b/ncrypt/pgpkey.c
index 976c2d0d9..475bca7bc 100644
--- a/ncrypt/pgpkey.c
+++ b/ncrypt/pgpkey.c
@@ -150,21 +150,7 @@ struct PgpEntry
 };
 
 /**
- * pgp_entry_fmt - Format an entry on the PGP 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)
- *
- * pgp_entry_fmt() is a callback function for mutt_expando_format().
+ * pgp_entry_fmt - Format an entry on the PGP key selection menu - Implements ::format_t
  *
  * | Expando | Description
  * |:--------|:--------------------------------------------------------
diff --git a/ncrypt/smime.c b/ncrypt/smime.c
index e58c5b9b3..3881e5a93 100644
--- a/ncrypt/smime.c
+++ b/ncrypt/smime.c
@@ -193,21 +193,7 @@ int smime_class_valid_passphrase(void)
  */
 
 /**
- * fmt_smime_command - Format an SMIME command
- * @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)
- *
- * fmt_smime_command() is a callback function for mutt_expando_format().
+ * fmt_smime_command - Format an SMIME command - Implements ::format_t
  *
  * | Expando | Description
  * |:--------|:-----------------------------------------------------------------
diff --git a/nntp/newsrc.c b/nntp/newsrc.c
index 2e1a1ff51..e3997e49a 100644
--- a/nntp/newsrc.c
+++ b/nntp/newsrc.c
@@ -942,21 +942,7 @@ void nntp_clear_cache(struct NntpServer *nserv)
 }
 
 /**
- * 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)
- *
- * nntp_format_str() is a callback function for mutt_expando_format().
+ * nntp_format_str - Expand the newsrc filename - Implements ::format_t
  *
  * | Expando | Description
  * |:--------|:--------------------------------------------------------
diff --git a/query.c b/query.c
index 28e973a17..4cf6c8294 100644
--- a/query.c
+++ b/query.c
@@ -233,21 +233,7 @@ static int query_search(struct Menu *m, regex_t *re, int n)
 }
 
 /**
- * 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().
+ * query_format_str - Format a string for the query menu - Implements ::format_t
  *
  * | Expando | Description
  * |:--------|:--------------------------------------------------------
diff --git a/recvattach.c b/recvattach.c
index e2b5258b5..4372b37a8 100644
--- a/recvattach.c
+++ b/recvattach.c
@@ -174,21 +174,7 @@ void mutt_update_tree(struct AttachCtx *actx)
 }
 
 /**
- * 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().
+ * attach_format_str - Format a string for the attachment menu - Implements ::format_t
  *
  * | Expando | Description
  * |:--------|:--------------------------------------------------------
diff --git a/remailer.c b/remailer.c
index cf4cb177a..9094daa53 100644
--- a/remailer.c
+++ b/remailer.c
@@ -414,21 +414,7 @@ static const char *mix_format_caps(struct Remailer *r)
 }
 
 /**
- * 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)
- *
- * mix_format_str() is a callback function for mutt_expando_format().
+ * mix_format_str - Format a string for the remailer menu - Implements ::format_t
  *
  * | Expando | Description
  * |:--------|:--------------------------------------------------------
diff --git a/sidebar.c b/sidebar.c
index 036b738e0..a27fae311 100644
--- a/sidebar.c
+++ b/sidebar.c
@@ -107,21 +107,7 @@ enum SidebarSrc
 } sidebar_source = SB_SRC_INCOMING;
 
 /**
- * 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().
+ * sidebar_format_str - Format a string for the sidebar - Implements ::format_t
  *
  * | Expando | Description
  * |:--------|:--------------------------------------------------------
diff --git a/status.c b/status.c
index 220ac4cfb..de2473931 100644
--- a/status.c
+++ b/status.c
@@ -66,21 +66,7 @@ static void status_line(char *buf, size_t buflen, size_t col, int cols,
                         struct Menu *menu, const char *p);
 
 /**
- * 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().
+ * status_format_str - Create the status bar string - Implements ::format_t
  *
  * | Expando | Description
  * |:--------|:--------------------------------------------------------