From: Richard Russon <rich@flatcap.org>
Date: Fri, 20 Jul 2018 02:39:06 +0000 (+0100)
Subject: doxygen: lots of docs
X-Git-Tag: 2019-10-25~745
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=9ba2b9cc4fb296a35134b8659310bd6b58f739fd;p=neomutt

doxygen: lots of docs
---

diff --git a/curs_main.c b/curs_main.c
index b0bad9ff3..13a2f8648 100644
--- a/curs_main.c
+++ b/curs_main.c
@@ -166,7 +166,7 @@ static const char *NoVisible = N_("No visible messages.");
   ((CollapseUnread || !UNREAD(header)) && (CollapseFlagged || !FLAGGED(header)))
 
 /**
- * collapse/uncollapse all threads
+ * collapse_all - Collapse/uncollapse all threads
  * @param menu   current menu
  * @param toggle toggle collapsed state
  *
diff --git a/ncrypt/crypt.c b/ncrypt/crypt.c
index e5eb93858..154765099 100644
--- a/ncrypt/crypt.c
+++ b/ncrypt/crypt.c
@@ -117,6 +117,9 @@ void crypt_forget_passphrase(void)
 
 #ifndef DEBUG
 #include <sys/resource.h>
+/**
+ * disable_coredumps - Prevent coredumps if neomutt were to crash
+ */
 static void disable_coredumps(void)
 {
   struct rlimit rl = { 0, 0 };
@@ -153,6 +156,13 @@ int crypt_valid_passphrase(int flags)
   return rc;
 }
 
+/**
+ * mutt_protect - Encrypt and/or sign a message
+ * @param msg     Header of the message
+ * @param keylist List of keys to encrypt to (space-separated)
+ * @retval  0 Success
+ * @retval -1 Error
+ */
 int mutt_protect(struct Header *msg, char *keylist)
 {
   struct Body *pbody = NULL, *tmp_pbody = NULL;
@@ -337,6 +347,12 @@ int mutt_protect(struct Header *msg, char *keylist)
   return 0;
 }
 
+/**
+ * mutt_is_multipart_signed - Is a message signed?
+ * @param b Body of email
+ * @retval >0 Message is signed, e.g. #PGPSIGN
+ * @retval  0 Message is not signed
+ */
 int mutt_is_multipart_signed(struct Body *b)
 {
   char *p = NULL;
@@ -374,6 +390,12 @@ int mutt_is_multipart_signed(struct Body *b)
   return 0;
 }
 
+/**
+ * mutt_is_multipart_encrypted - Does the message have encrypted parts?
+ * @param b Body of email
+ * @retval >0 Message has got encrypted parts, e.g. #PGPENCRYPT
+ * @retval  0 Message hasn't got encrypted parts
+ */
 int mutt_is_multipart_encrypted(struct Body *b)
 {
   if ((WithCrypto & APPLICATION_PGP) == 0)
@@ -392,6 +414,12 @@ int mutt_is_multipart_encrypted(struct Body *b)
   return PGPENCRYPT;
 }
 
+/**
+ * mutt_is_valid_multipart_pgp_encrypted - Is this a valid multi-part encrypted message?
+ * @param b Body of email
+ * @retval >0 Message is valid, with encrypted parts, e.g. #PGPENCRYPT
+ * @retval  0 Message hasn't got encrypted parts
+ */
 int mutt_is_valid_multipart_pgp_encrypted(struct Body *b)
 {
   if (mutt_is_multipart_encrypted(b) == 0)
@@ -469,6 +497,12 @@ int mutt_is_malformed_multipart_pgp_encrypted(struct Body *b)
   return PGPENCRYPT;
 }
 
+/**
+ * mutt_is_application_pgp - Does the message use PGP?
+ * @param m Body of email
+ * @retval >0 Message uses PGP, e.g. #PGPENCRYPT
+ * @retval  0 Message doesn't use PGP
+ */
 int mutt_is_application_pgp(struct Body *m)
 {
   int t = 0;
@@ -522,6 +556,12 @@ int mutt_is_application_pgp(struct Body *m)
   return t;
 }
 
+/**
+ * mutt_is_application_smime - Does the message use S/MIME?
+ * @param m Body of email
+ * @retval >0 Message uses S/MIME, e.g. #SMIMEENCRYPT
+ * @retval  0 Message doesn't use S/MIME
+ */
 int mutt_is_application_smime(struct Body *m)
 {
   if (!m)
@@ -715,6 +755,10 @@ int crypt_write_signed(struct Body *a, struct State *s, const char *tempfile)
   return 0;
 }
 
+/**
+ * crypt_convert_to_7bit - Convert an email to 7bit encoding
+ * @param a Body of email to convert
+ */
 void crypt_convert_to_7bit(struct Body *a)
 {
   if (!WithCrypto)
@@ -751,6 +795,12 @@ void crypt_convert_to_7bit(struct Body *a)
   }
 }
 
+/**
+ * crypt_extract_keys_from_messages - Extract keys from a message
+ * @param h Header of email
+ *
+ * The extracted keys will be added to the user's keyring.
+ */
 void crypt_extract_keys_from_messages(struct Header *h)
 {
   char tempfname[PATH_MAX], *mbox = NULL;
@@ -984,6 +1034,12 @@ void crypt_opportunistic_encrypt(struct Header *msg)
   }
 }
 
+/**
+ * crypt_fetch_signatures - Create an array of an emails parts
+ * @param[out] signatures Array of Body parts
+ * @param[in]  a          Body part to examine
+ * @param[out] n          Cumulative count of parts
+ */
 static void crypt_fetch_signatures(struct Body ***signatures, struct Body *a, int *n)
 {
   if (!WithCrypto)
diff --git a/ncrypt/crypt_gpgme.c b/ncrypt/crypt_gpgme.c
index 52cf1457f..6ff6ae436 100644
--- a/ncrypt/crypt_gpgme.c
+++ b/ncrypt/crypt_gpgme.c
@@ -5201,6 +5201,10 @@ void pgp_gpgme_set_sender(const char *sender)
   current_sender = mutt_str_strdup(sender);
 }
 
+/**
+ * mutt_gpgme_print_version - Get version of GPGME
+ * @retval ptr GPGME version string
+ */
 const char *mutt_gpgme_print_version(void)
 {
   return GPGME_VERSION;
diff --git a/ncrypt/pgp.c b/ncrypt/pgp.c
index dabd3ce3c..6a20342e2 100644
--- a/ncrypt/pgp.c
+++ b/ncrypt/pgp.c
@@ -115,6 +115,12 @@ int pgp_class_valid_passphrase(void)
   return 0;
 }
 
+/**
+ * pgp_use_gpg_agent - Does the user want to use the gpg agent?
+ * @retval true If they do
+ *
+ * @note This functions sets the environment variable `$GPG_TTY`
+ */
 bool pgp_use_gpg_agent(void)
 {
   char *tty = NULL;
@@ -133,6 +139,11 @@ bool pgp_use_gpg_agent(void)
   return true;
 }
 
+/**
+ * key_parent - Find a key's parent (if it's a subkey)
+ * @param k PGP key
+ * @retval ptr Parent key
+ */
 static struct PgpKeyInfo *key_parent(struct PgpKeyInfo *k)
 {
   if ((k->flags & KEYFLAG_SUBKEY) && k->parent && PgpIgnoreSubkeys)
@@ -141,6 +152,11 @@ static struct PgpKeyInfo *key_parent(struct PgpKeyInfo *k)
   return k;
 }
 
+/**
+ * pgp_long_keyid - Get a key's long id
+ * @param k PGP key
+ * @retval ptr Long key id string
+ */
 char *pgp_long_keyid(struct PgpKeyInfo *k)
 {
   k = key_parent(k);
@@ -148,6 +164,11 @@ char *pgp_long_keyid(struct PgpKeyInfo *k)
   return k->keyid;
 }
 
+/**
+ * pgp_short_keyid - Get a key's short id
+ * @param k PGP key
+ * @retval ptr Short key id string
+ */
 char *pgp_short_keyid(struct PgpKeyInfo *k)
 {
   k = key_parent(k);
@@ -155,6 +176,13 @@ char *pgp_short_keyid(struct PgpKeyInfo *k)
   return k->keyid + 8;
 }
 
+/**
+ * pgp_this_keyid - Get the ID of this key
+ * @param k PGP key
+ * @retval ptr Long/Short key id string
+ *
+ * @note The string returned depends on `$pgp_long_ids`
+ */
 char *pgp_this_keyid(struct PgpKeyInfo *k)
 {
   if (PgpLongIds)
@@ -163,6 +191,11 @@ char *pgp_this_keyid(struct PgpKeyInfo *k)
     return k->keyid + 8;
 }
 
+/**
+ * pgp_keyid - Get the ID of the main (parent) key
+ * @param k PGP key
+ * @retval ptr Long/Short key id string
+ */
 char *pgp_keyid(struct PgpKeyInfo *k)
 {
   k = key_parent(k);
@@ -170,6 +203,11 @@ char *pgp_keyid(struct PgpKeyInfo *k)
   return pgp_this_keyid(k);
 }
 
+/**
+ * pgp_fingerprint - Get the key's fingerprint
+ * @param k PGP key
+ * @retval ptr Fingerprint string
+ */
 static char *pgp_fingerprint(struct PgpKeyInfo *k)
 {
   k = key_parent(k);
@@ -246,7 +284,7 @@ static int pgp_copy_checksig(FILE *fpin, FILE *fpout)
 }
 
 /**
- * pgp_check_decryption_okay - Check PGP output to look for successful outcome
+ * pgp_check_pgp_decryption_okay_regex - Check PGP output to look for successful outcome
  * @param fpin File to read from
  * @retval  0 Success
  * @retval -1 Error
@@ -729,6 +767,13 @@ out:
   return rc;
 }
 
+/**
+ * pgp_check_traditional_one_body - Check the body of an inline PGP message
+ * @param fp File to read
+ * @param b  Body to populate
+ * @retval 1 Success
+ * @retval 0 Error
+ */
 static int pgp_check_traditional_one_body(FILE *fp, struct Body *b)
 {
   char tempfile[PATH_MAX];
@@ -927,6 +972,14 @@ void pgp_class_extract_key_from_attachment(FILE *fp, struct Body *top)
   OptDontHandlePgpKeys = false;
 }
 
+/**
+ * pgp_decrypt_part - Decrypt part of a PGP message
+ * @param a     Body of attachment
+ * @param s     State to use
+ * @param fpout File to write to
+ * @param p     Body of parent (main email)
+ * @retval ptr New Body for the attachment
+ */
 static struct Body *pgp_decrypt_part(struct Body *a, struct State *s,
                                      FILE *fpout, struct Body *p)
 {
diff --git a/ncrypt/pgpinvoke.c b/ncrypt/pgpinvoke.c
index dc03f275c..71cdff400 100644
--- a/ncrypt/pgpinvoke.c
+++ b/ncrypt/pgpinvoke.c
@@ -78,6 +78,31 @@ struct PgpCommandContext
   const char *ids;       /**< %r */
 };
 
+/**
+ * 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().
+ *
+ * | Expando | Description
+ * |:--------|:-----------------------------------------------------------------
+ * | \%a     | Value of $pgp_sign_as if set, otherwise $pgp_default_key
+ * | \%f     | File containing a message
+ * | \%p     | Expands to PGPPASSFD=0 when a pass phrase is needed, to an empty string otherwise
+ * | \%r     | One or more key IDs (or fingerprints if available)
+ * | \%s     | File containing the signature part of a multipart/signed attachment when verifying it
+ */
 static const char *fmt_pgp_command(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,
@@ -159,6 +184,13 @@ static const char *fmt_pgp_command(char *buf, size_t buflen, size_t col, int col
   return src;
 }
 
+/**
+ * mutt_pgp_command - Prepare a PGP Command
+ * @param buf    Buffer for the result
+ * @param buflen Length of buffer
+ * @param cctx   Data to pass to the formatter
+ * @param fmt    printf-like formatting string
+ */
 static void mutt_pgp_command(char *buf, size_t buflen,
                              struct PgpCommandContext *cctx, const char *fmt)
 {
@@ -167,6 +199,25 @@ static void mutt_pgp_command(char *buf, size_t buflen,
   mutt_debug(2, "%s\n", buf);
 }
 
+/**
+ * pgp_invoke - Run a PGP command
+ * @param pgpin           stdin  for the command, or NULL (OPTIONAL)
+ * @param pgpout          stdout for the command, or NULL (OPTIONAL)
+ * @param pgperr          stderr for the command, or NULL (OPTIONAL)
+ * @param pgpinfd         stdin  for the command, or -1 (OPTIONAL)
+ * @param pgpoutfd        stdout for the command, or -1 (OPTIONAL)
+ * @param pgperrfd        stderr for the command, or -1 (OPTIONAL)
+ * @param need_passphrase Is a passphrase needed?
+ * @param fname           Filename to pass to the command
+ * @param sig_fname       Signature filename to pass to the command
+ * @param ids             List of IDs/fingerprints, space separated
+ * @param format          printf-like format string
+ * @retval num PID of the created process
+ * @retval -1  Error creating pipes or forking
+ *
+ * @note `pgpin` has priority over `pgpinfd`.
+ *       Likewise `pgpout` and `pgperr`.
+ */
 static pid_t pgp_invoke(FILE **pgpin, FILE **pgpout, FILE **pgperr, int pgpinfd, int pgpoutfd,
                         int pgperrfd, bool need_passphrase, const char *fname,
                         const char *sig_fname, const char *ids, const char *format)
@@ -197,6 +248,22 @@ static pid_t pgp_invoke(FILE **pgpin, FILE **pgpout, FILE **pgperr, int pgpinfd,
  * This is historic and may be removed at some point.
  */
 
+/**
+ * pgp_invoke_decode - Use PGP to decode a message
+ * @param pgpin           stdin  for the command, or NULL (OPTIONAL)
+ * @param pgpout          stdout for the command, or NULL (OPTIONAL)
+ * @param pgperr          stderr for the command, or NULL (OPTIONAL)
+ * @param pgpinfd         stdin  for the command, or -1 (OPTIONAL)
+ * @param pgpoutfd        stdout for the command, or -1 (OPTIONAL)
+ * @param pgperrfd        stderr for the command, or -1 (OPTIONAL)
+ * @param fname           Filename to pass to the command
+ * @param need_passphrase Is a passphrase needed?
+ * @retval num PID of the created process
+ * @retval -1  Error creating pipes or forking
+ *
+ * @note `pgpin` has priority over `pgpinfd`.
+ *       Likewise `pgpout` and `pgperr`.
+ */
 pid_t pgp_invoke_decode(FILE **pgpin, FILE **pgpout, FILE **pgperr, int pgpinfd,
                         int pgpoutfd, int pgperrfd, const char *fname, bool need_passphrase)
 {
@@ -204,6 +271,22 @@ pid_t pgp_invoke_decode(FILE **pgpin, FILE **pgpout, FILE **pgperr, int pgpinfd,
                     need_passphrase, fname, NULL, NULL, PgpDecodeCommand);
 }
 
+/**
+ * pgp_invoke_verify - Use PGP to verify a message
+ * @param pgpin     stdin  for the command, or NULL (OPTIONAL)
+ * @param pgpout    stdout for the command, or NULL (OPTIONAL)
+ * @param pgperr    stderr for the command, or NULL (OPTIONAL)
+ * @param pgpinfd   stdin  for the command, or -1 (OPTIONAL)
+ * @param pgpoutfd  stdout for the command, or -1 (OPTIONAL)
+ * @param pgperrfd  stderr for the command, or -1 (OPTIONAL)
+ * @param fname     Filename to pass to the command
+ * @param sig_fname Signature filename to pass to the command
+ * @retval num PID of the created process
+ * @retval -1  Error creating pipes or forking
+ *
+ * @note `pgpin` has priority over `pgpinfd`.
+ *       Likewise `pgpout` and `pgperr`.
+ */
 pid_t pgp_invoke_verify(FILE **pgpin, FILE **pgpout, FILE **pgperr, int pgpinfd,
                         int pgpoutfd, int pgperrfd, const char *fname, const char *sig_fname)
 {
@@ -211,6 +294,21 @@ pid_t pgp_invoke_verify(FILE **pgpin, FILE **pgpout, FILE **pgperr, int pgpinfd,
                     fname, sig_fname, NULL, PgpVerifyCommand);
 }
 
+/**
+ * pgp_invoke_decrypt - Use PGP to decrypt a file
+ * @param pgpin    stdin  for the command, or NULL (OPTIONAL)
+ * @param pgpout   stdout for the command, or NULL (OPTIONAL)
+ * @param pgperr   stderr for the command, or NULL (OPTIONAL)
+ * @param pgpinfd  stdin  for the command, or -1 (OPTIONAL)
+ * @param pgpoutfd stdout for the command, or -1 (OPTIONAL)
+ * @param pgperrfd stderr for the command, or -1 (OPTIONAL)
+ * @param fname    Filename to pass to the command
+ * @retval num PID of the created process
+ * @retval -1  Error creating pipes or forking
+ *
+ * @note `pgpin` has priority over `pgpinfd`.
+ *       Likewise `pgpout` and `pgperr`.
+ */
 pid_t pgp_invoke_decrypt(FILE **pgpin, FILE **pgpout, FILE **pgperr, int pgpinfd,
                          int pgpoutfd, int pgperrfd, const char *fname)
 {
@@ -218,6 +316,21 @@ pid_t pgp_invoke_decrypt(FILE **pgpin, FILE **pgpout, FILE **pgperr, int pgpinfd
                     fname, NULL, NULL, PgpDecryptCommand);
 }
 
+/**
+ * pgp_invoke_sign - Use PGP to sign a file
+ * @param pgpin    stdin  for the command, or NULL (OPTIONAL)
+ * @param pgpout   stdout for the command, or NULL (OPTIONAL)
+ * @param pgperr   stderr for the command, or NULL (OPTIONAL)
+ * @param pgpinfd  stdin  for the command, or -1 (OPTIONAL)
+ * @param pgpoutfd stdout for the command, or -1 (OPTIONAL)
+ * @param pgperrfd stderr for the command, or -1 (OPTIONAL)
+ * @param fname    Filename to pass to the command
+ * @retval num PID of the created process
+ * @retval -1  Error creating pipes or forking
+ *
+ * @note `pgpin` has priority over `pgpinfd`.
+ *       Likewise `pgpout` and `pgperr`.
+ */
 pid_t pgp_invoke_sign(FILE **pgpin, FILE **pgpout, FILE **pgperr, int pgpinfd,
                       int pgpoutfd, int pgperrfd, const char *fname)
 {
@@ -225,6 +338,23 @@ pid_t pgp_invoke_sign(FILE **pgpin, FILE **pgpout, FILE **pgperr, int pgpinfd,
                     fname, NULL, NULL, PgpSignCommand);
 }
 
+/**
+ * pgp_invoke_encrypt - Use PGP to encrypt a file
+ * @param pgpin    stdin  for the command, or NULL (OPTIONAL)
+ * @param pgpout   stdout for the command, or NULL (OPTIONAL)
+ * @param pgperr   stderr for the command, or NULL (OPTIONAL)
+ * @param pgpinfd  stdin  for the command, or -1 (OPTIONAL)
+ * @param pgpoutfd stdout for the command, or -1 (OPTIONAL)
+ * @param pgperrfd stderr for the command, or -1 (OPTIONAL)
+ * @param fname    Filename to pass to the command
+ * @param uids     List of IDs/fingerprints, space separated
+ * @param sign     If true, also sign the file
+ * @retval num PID of the created process
+ * @retval -1  Error creating pipes or forking
+ *
+ * @note `pgpin` has priority over `pgpinfd`.
+ *       Likewise `pgpout` and `pgperr`.
+ */
 pid_t pgp_invoke_encrypt(FILE **pgpin, FILE **pgpout, FILE **pgperr,
                          int pgpinfd, int pgpoutfd, int pgperrfd,
                          const char *fname, const char *uids, bool sign)
@@ -241,6 +371,23 @@ pid_t pgp_invoke_encrypt(FILE **pgpin, FILE **pgpout, FILE **pgperr,
   }
 }
 
+/**
+ * pgp_invoke_traditional - Use PGP to create in inline-signed message
+ * @param pgpin    stdin  for the command, or NULL (OPTIONAL)
+ * @param pgpout   stdout for the command, or NULL (OPTIONAL)
+ * @param pgperr   stderr for the command, or NULL (OPTIONAL)
+ * @param pgpinfd  stdin  for the command, or -1 (OPTIONAL)
+ * @param pgpoutfd stdout for the command, or -1 (OPTIONAL)
+ * @param pgperrfd stderr for the command, or -1 (OPTIONAL)
+ * @param fname    Filename to pass to the command
+ * @param uids     List of IDs/fingerprints, space separated
+ * @param flags    Flags, e.g. #SIGN, #ENCRYPT
+ * @retval num PID of the created process
+ * @retval -1  Error creating pipes or forking
+ *
+ * @note `pgpin` has priority over `pgpinfd`.
+ *       Likewise `pgpout` and `pgperr`.
+ */
 pid_t pgp_invoke_traditional(FILE **pgpin, FILE **pgpout, FILE **pgperr,
                              int pgpinfd, int pgpoutfd, int pgperrfd,
                              const char *fname, const char *uids, int flags)
@@ -325,6 +472,21 @@ void pgp_class_invoke_getkeys(struct Address *addr)
     close(devnull);
 }
 
+/**
+ * pgp_invoke_export - Use PGP to export a key from the user's keyring
+ * @param pgpin    stdin  for the command, or NULL (OPTIONAL)
+ * @param pgpout   stdout for the command, or NULL (OPTIONAL)
+ * @param pgperr   stderr for the command, or NULL (OPTIONAL)
+ * @param pgpinfd  stdin  for the command, or -1 (OPTIONAL)
+ * @param pgpoutfd stdout for the command, or -1 (OPTIONAL)
+ * @param pgperrfd stderr for the command, or -1 (OPTIONAL)
+ * @param uids     List of IDs/fingerprints, space separated
+ * @retval num PID of the created process
+ * @retval -1  Error creating pipes or forking
+ *
+ * @note `pgpin` has priority over `pgpinfd`.
+ *       Likewise `pgpout` and `pgperr`.
+ */
 pid_t pgp_invoke_export(FILE **pgpin, FILE **pgpout, FILE **pgperr, int pgpinfd,
                         int pgpoutfd, int pgperrfd, const char *uids)
 {
@@ -332,6 +494,21 @@ pid_t pgp_invoke_export(FILE **pgpin, FILE **pgpout, FILE **pgperr, int pgpinfd,
                     NULL, NULL, uids, PgpExportCommand);
 }
 
+/**
+ * pgp_invoke_verify_key - Use PGP to verify a key
+ * @param pgpin    stdin  for the command, or NULL (OPTIONAL)
+ * @param pgpout   stdout for the command, or NULL (OPTIONAL)
+ * @param pgperr   stderr for the command, or NULL (OPTIONAL)
+ * @param pgpinfd  stdin  for the command, or -1 (OPTIONAL)
+ * @param pgpoutfd stdout for the command, or -1 (OPTIONAL)
+ * @param pgperrfd stderr for the command, or -1 (OPTIONAL)
+ * @param uids     List of IDs/fingerprints, space separated
+ * @retval num PID of the created process
+ * @retval -1  Error creating pipes or forking
+ *
+ * @note `pgpin` has priority over `pgpinfd`.
+ *       Likewise `pgpout` and `pgperr`.
+ */
 pid_t pgp_invoke_verify_key(FILE **pgpin, FILE **pgpout, FILE **pgperr, int pgpinfd,
                             int pgpoutfd, int pgperrfd, const char *uids)
 {
@@ -341,16 +518,19 @@ pid_t pgp_invoke_verify_key(FILE **pgpin, FILE **pgpout, FILE **pgperr, int pgpi
 
 /**
  * pgp_invoke_list_keys - Find matching PGP Keys
- * @param pgpin    File stream pointing to stdin for the command process, can be NULL
- * @param pgpout   File stream pointing to stdout for the command process, can be NULL
- * @param pgperr   File stream pointing to stderr for the command process, can be NULL
- * @param pgpinfd  If `pgpin` is NULL and pgpin is not -1 then pgpin will be used as stdin for the command process
- * @param pgpoutfd If `pgpout` is NULL and pgpout is not -1 then pgpout will be used as stdout for the command process
- * @param pgperrfd If `pgperr` is NULL and pgperr is not -1 then pgperr will be used as stderr for the command process
+ * @param pgpin  stdin  for the command, or NULL (OPTIONAL)
+ * @param pgpout stdout for the command, or NULL (OPTIONAL)
+ * @param pgperr stderr for the command, or NULL (OPTIONAL)
+ * @param pgpinfd  stdin  for the command, or -1 (OPTIONAL)
+ * @param pgpoutfd stdout for the command, or -1 (OPTIONAL)
+ * @param pgperrfd stderr for the command, or -1 (OPTIONAL)
  * @param keyring  Keyring type, e.g. #PGP_SECRING
  * @param hints    Match keys to these strings
- * @retval num  PID of the created process
- * @retval -1   Error creating pipes or forking
+ * @retval num PID of the created process
+ * @retval -1  Error creating pipes or forking
+ *
+ * @note `pgpin` has priority over `pgpinfd`.
+ *       Likewise `pgpout` and `pgperr`.
  */
 pid_t pgp_invoke_list_keys(FILE **pgpin, FILE **pgpout, FILE **pgperr,
                            int pgpinfd, int pgpoutfd, int pgperrfd,
diff --git a/ncrypt/pgplib.c b/ncrypt/pgplib.c
index 5c3824910..9aa68c26d 100644
--- a/ncrypt/pgplib.c
+++ b/ncrypt/pgplib.c
@@ -31,6 +31,11 @@
 #include "mutt/mutt.h"
 #include "pgplib.h"
 
+/**
+ * pgp_pkalgbytype - Get the name of the algorithm from its ID
+ * @param type Algorithm ID
+ * @retval ptr Algorithm name
+ */
 const char *pgp_pkalgbytype(unsigned char type)
 {
   switch (type)
@@ -52,6 +57,11 @@ const char *pgp_pkalgbytype(unsigned char type)
   }
 }
 
+/**
+ * pgp_canencrypt - Does this algorithm ID support encryption?
+ * @param type Algorithm ID
+ * @retval true If it does
+ */
 bool pgp_canencrypt(unsigned char type)
 {
   switch (type)
@@ -66,6 +76,11 @@ bool pgp_canencrypt(unsigned char type)
   }
 }
 
+/**
+ * pgp_cansign - Does this algorithm ID support signing?
+ * @param type Algorithm ID
+ * @retval true If it does
+ */
 bool pgp_cansign(unsigned char type)
 {
   switch (type)
@@ -80,11 +95,24 @@ bool pgp_cansign(unsigned char type)
   }
 }
 
+/**
+ * pgp_get_abilities - Get the capabilities of an algorithm
+ * @param type Algorithm ID
+ * @retval num Capabilities
+ *
+ * The abilities are OR'd together
+ * - 1 If signing is possible
+ * - 2 If encryption is possible
+ */
 short pgp_get_abilities(unsigned char type)
 {
   return (pgp_canencrypt(type) << 1) | pgp_cansign(type);
 }
 
+/**
+ * pgp_free_uid - Free a PGP UID
+ * @param upp PGP UID to free
+ */
 static void pgp_free_uid(struct PgpUid **upp)
 {
   struct PgpUid *up = NULL, *q = NULL;
@@ -101,6 +129,12 @@ static void pgp_free_uid(struct PgpUid **upp)
   *upp = NULL;
 }
 
+/**
+ * pgp_copy_uids - Copy a list of PGP UIDs
+ * @param up     List of PGP UIDs
+ * @param parent Parent PGP key
+ * @retval ptr New list of PGP UIDs
+ */
 struct PgpUid *pgp_copy_uids(struct PgpUid *up, struct PgpKeyInfo *parent)
 {
   struct PgpUid *l = NULL;
@@ -119,6 +153,10 @@ struct PgpUid *pgp_copy_uids(struct PgpUid *up, struct PgpKeyInfo *parent)
   return l;
 }
 
+/**
+ * free_key - Free a PGP Key info
+ * @param kpp PGP Key info to free
+ */
 static void free_key(struct PgpKeyInfo **kpp)
 {
   struct PgpKeyInfo *kp = NULL;
@@ -134,6 +172,12 @@ static void free_key(struct PgpKeyInfo **kpp)
   FREE(kpp);
 }
 
+/**
+ * pgp_remove_key - Remove a PGP key from a list
+ * @param klist List of PGP Keys
+ * @param key   Key to remove
+ * @retval ptr Updated list of PGP Keys
+ */
 struct PgpKeyInfo *pgp_remove_key(struct PgpKeyInfo **klist, struct PgpKeyInfo *key)
 {
   struct PgpKeyInfo **last = NULL;
@@ -162,6 +206,10 @@ struct PgpKeyInfo *pgp_remove_key(struct PgpKeyInfo **klist, struct PgpKeyInfo *
   return q;
 }
 
+/**
+ * pgp_free_key - Free a PGP key info
+ * @param kpp PGP key info to free
+ */
 void pgp_free_key(struct PgpKeyInfo **kpp)
 {
   struct PgpKeyInfo *p = NULL, *q = NULL, *r = NULL;
diff --git a/ncrypt/pgpmicalg.c b/ncrypt/pgpmicalg.c
index 57d5abd79..39e4c5bca 100644
--- a/ncrypt/pgpmicalg.c
+++ b/ncrypt/pgpmicalg.c
@@ -23,7 +23,7 @@
 /**
  * @page crypt_pgpmicalg Identify the hash algorithm from a PGP signature
  *
- * Identify the hash algorithm from a PGP signature
+ * Identify the Message Integrity Check algorithm (micalg) from a PGP signature
  */
 
 #include "config.h"
@@ -47,6 +47,11 @@ static const struct
   { 11, "pgp-sha224" }, { -1, NULL },
 };
 
+/**
+ * pgp_hash_to_micalg - Lookup a hash name, given its id
+ * @param id ID
+ * @retval ptr Name of hash algorithm
+ */
 static const char *pgp_hash_to_micalg(short id)
 {
   for (int i = 0; HashAlgorithms[i].id >= 0; i++)
@@ -55,6 +60,11 @@ static const char *pgp_hash_to_micalg(short id)
   return "x-unknown";
 }
 
+/**
+ * pgp_dearmor - Unwrap an armoured PGP block
+ * @param in  File to read from
+ * @param out File to write to
+ */
 static void pgp_dearmor(FILE *in, FILE *out)
 {
   char line[HUGE_STRING];
@@ -127,6 +137,12 @@ static void pgp_dearmor(FILE *in, FILE *out)
   mutt_decode_base64(&state, end - start, false, (iconv_t) -1);
 }
 
+/**
+ * pgp_mic_from_packet - Get the hash algorithm from a PGP packet
+ * @param p   PGP packet
+ * @param len Length of packet
+ * @retval num Hash algorithm id
+ */
 static short pgp_mic_from_packet(unsigned char *p, size_t len)
 {
   /* is signature? */
@@ -153,6 +169,11 @@ static short pgp_mic_from_packet(unsigned char *p, size_t len)
   }
 }
 
+/**
+ * pgp_find_hash - Find the hash algorithm of a file
+ * @param fname File to read
+ * @retval num Hash algorithm id
+ */
 static short pgp_find_hash(const char *fname)
 {
   size_t l;
@@ -193,6 +214,11 @@ bye:
   return rc;
 }
 
+/**
+ * pgp_micalg - Find the hash algorithm of a file
+ * @param fname File to read
+ * @retval ptr Name of hash algorithm
+ */
 const char *pgp_micalg(const char *fname)
 {
   return pgp_hash_to_micalg(pgp_find_hash(fname));
diff --git a/ncrypt/smime.c b/ncrypt/smime.c
index 7f50fde21..fe65bf126 100644
--- a/ncrypt/smime.c
+++ b/ncrypt/smime.c
@@ -197,8 +197,6 @@ int smime_class_valid_passphrase(void)
  * @param[in]  flags    Format flags
  * @retval src (unchanged)
  *
- * This is almost identical to pgp's invoking interface.
- *
  * fmt_smime_command() is a callback function for mutt_expando_format().
  *
  * | Expando | Description
@@ -353,6 +351,28 @@ static void smime_command(char *buf, size_t buflen,
   mutt_debug(2, "%s\n", buf);
 }
 
+/**
+ * smime_invoke - Run an SMIME command
+ * @param smimein       stdin  for the command, or NULL (OPTIONAL)
+ * @param smimeout      stdout for the command, or NULL (OPTIONAL)
+ * @param smimeerr      stderr for the command, or NULL (OPTIONAL)
+ * @param smimeinfd     stdin  for the command, or -1 (OPTIONAL)
+ * @param smimeoutfd    stdout for the command, or -1 (OPTIONAL)
+ * @param smimeerrfd    stderr for the command, or -1 (OPTIONAL)
+ * @param fname         Filename to pass to the command
+ * @param sig_fname     Signature filename to pass to the command
+ * @param cryptalg      Encryption algorithm
+ * @param digestalg     Hashing algorithm
+ * @param key           SMIME key
+ * @param certificates  Public certificates
+ * @param intermediates Intermediate certificates
+ * @param format        printf-like format string
+ * @retval num PID of the created process
+ * @retval -1  Error creating pipes or forking
+ *
+ * @note `smimein` has priority over `smimeinfd`.
+ *       Likewise `smimeout` and `smimeerr`.
+ */
 static pid_t smime_invoke(FILE **smimein, FILE **smimeout, FILE **smimeerr,
                           int smimeinfd, int smimeoutfd, int smimeerrfd,
                           const char *fname, const char *sig_fname, const char *cryptalg,
@@ -1399,6 +1419,22 @@ int smime_class_verify_sender(struct Header *h)
  *    Creating S/MIME - bodies.
  */
 
+/**
+ * smime_invoke_encrypt - Use SMIME to encrypt a file
+ * @param smimein    stdin  for the command, or NULL (OPTIONAL)
+ * @param smimeout   stdout for the command, or NULL (OPTIONAL)
+ * @param smimeerr   stderr for the command, or NULL (OPTIONAL)
+ * @param smimeinfd  stdin  for the command, or -1 (OPTIONAL)
+ * @param smimeoutfd stdout for the command, or -1 (OPTIONAL)
+ * @param smimeerrfd stderr for the command, or -1 (OPTIONAL)
+ * @param fname      Filename to pass to the command
+ * @param uids       List of IDs/fingerprints, space separated
+ * @retval num PID of the created process
+ * @retval -1  Error creating pipes or forking
+ *
+ * @note `smimein` has priority over `smimeinfd`.
+ *       Likewise `smimeout` and `smimeerr`.
+ */
 static pid_t smime_invoke_encrypt(FILE **smimein, FILE **smimeout, FILE **smimeerr,
                                   int smimeinfd, int smimeoutfd, int smimeerrfd,
                                   const char *fname, const char *uids)
@@ -1408,6 +1444,21 @@ static pid_t smime_invoke_encrypt(FILE **smimein, FILE **smimeout, FILE **smimee
                       uids, NULL, SmimeEncryptCommand);
 }
 
+/**
+ * smime_invoke_sign - Use SMIME to sign a file
+ * @param smimein    stdin  for the command, or NULL (OPTIONAL)
+ * @param smimeout   stdout for the command, or NULL (OPTIONAL)
+ * @param smimeerr   stderr for the command, or NULL (OPTIONAL)
+ * @param smimeinfd  stdin  for the command, or -1 (OPTIONAL)
+ * @param smimeoutfd stdout for the command, or -1 (OPTIONAL)
+ * @param smimeerrfd stderr for the command, or -1 (OPTIONAL)
+ * @param fname      Filename to pass to the command
+ * @retval num PID of the created process
+ * @retval -1  Error creating pipes or forking
+ *
+ * @note `smimein` has priority over `smimeinfd`.
+ *       Likewise `smimeout` and `smimeerr`.
+ */
 static pid_t smime_invoke_sign(FILE **smimein, FILE **smimeout, FILE **smimeerr, int smimeinfd,
                                int smimeoutfd, int smimeerrfd, const char *fname)
 {
@@ -1711,6 +1762,23 @@ struct Body *smime_class_sign_message(struct Body *a)
  *    Handling S/MIME - bodies.
  */
 
+/**
+ * smime_invoke_verify - Use SMIME to verify a file
+ * @param smimein    stdin  for the command, or NULL (OPTIONAL)
+ * @param smimeout   stdout for the command, or NULL (OPTIONAL)
+ * @param smimeerr   stderr for the command, or NULL (OPTIONAL)
+ * @param smimeinfd  stdin  for the command, or -1 (OPTIONAL)
+ * @param smimeoutfd stdout for the command, or -1 (OPTIONAL)
+ * @param smimeerrfd stderr for the command, or -1 (OPTIONAL)
+ * @param fname      Filename to pass to the command
+ * @param sig_fname  Signature filename to pass to the command
+ * @param opaque     If true, use `$smime_verify_opaque_command` else `$smime_verify_command`
+ * @retval num PID of the created process
+ * @retval -1  Error creating pipes or forking
+ *
+ * @note `smimein` has priority over `smimeinfd`.
+ *       Likewise `smimeout` and `smimeerr`.
+ */
 static pid_t smime_invoke_verify(FILE **smimein, FILE **smimeout, FILE **smimeerr,
                                  int smimeinfd, int smimeoutfd, int smimeerrfd,
                                  const char *fname, const char *sig_fname, int opaque)
@@ -1720,6 +1788,21 @@ static pid_t smime_invoke_verify(FILE **smimein, FILE **smimeout, FILE **smimeer
                       (opaque ? SmimeVerifyOpaqueCommand : SmimeVerifyCommand));
 }
 
+/**
+ * smime_invoke_decrypt - Use SMIME to decrypt a file
+ * @param smimein    stdin  for the command, or NULL (OPTIONAL)
+ * @param smimeout   stdout for the command, or NULL (OPTIONAL)
+ * @param smimeerr   stderr for the command, or NULL (OPTIONAL)
+ * @param smimeinfd  stdin  for the command, or -1 (OPTIONAL)
+ * @param smimeoutfd stdout for the command, or -1 (OPTIONAL)
+ * @param smimeerrfd stderr for the command, or -1 (OPTIONAL)
+ * @param fname      Filename to pass to the command
+ * @retval num PID of the created process
+ * @retval -1  Error creating pipes or forking
+ *
+ * @note `smimein` has priority over `smimeinfd`.
+ *       Likewise `smimeout` and `smimeerr`.
+ */
 static pid_t smime_invoke_decrypt(FILE **smimein, FILE **smimeout,
                                   FILE **smimeerr, int smimeinfd, int smimeoutfd,
                                   int smimeerrfd, const char *fname)