docs: document some functions

diff --git a/attach.c b/attach.c
index 4d865bcfb1c89f595d2521321595aff6208179a4..e722b9d29b390ac9c9c98d03cab75970a2acbcc5 100644 (file)
--- a/attach.c
+++ b/attach.c
@@ -301,6 +301,12 @@ bailout:
 }
 
 
+/**
+ * mutt_check_lookup_list - Update the mime type
+ * @param b    Message attachment body
+ * @param type Buffer with mime type of attachment in "type/subtype" format
+ * @param len  Buffer length
+ */
 void mutt_check_lookup_list(struct Body *b, char *type, int len)
 {
   struct List *t = MimeLookupList;
@@ -343,9 +349,25 @@ void mutt_check_lookup_list(struct Body *b, char *type, int len)
 
 /**
  * mutt_view_attachment - View an attachment
+ * @param fp     Source file stream. Can be NULL
+ * @param a      The message body containing the attachment
+ * @param flag   Option flag for how the attachment should be viewed
+ * @param hdr    Message header for the current message. Can be NULL
+ * @param idx    Attachment
+ * @param idxlen Number of attachments
  * @return
+ * * 0 if the viewer is run and exited succesfully
  * * -1 on error
- * * 0 or the return code from mutt_do_pager() on success
+ * * The return value of mutt_do_pager() when it is used
+ *
+ * flag can be one of: #MUTT_MAILCAP, #MUTT_REGULAR, #MUTT_AS_TEXT
+ *
+ * Display a message attachment using the viewer program configured in mailcap.
+ * If there is no mailcap entry for a file type, view the image as text.
+ * Viewer processes are opened and waited on synchronously so viewing an
+ * attachment this way will block the main mutt process until the viewer process
+ * exits.
+ *
  */
 int mutt_view_attachment(FILE *fp, struct Body *a, int flag, struct Header *hdr,
                          struct AttachPtr **idx, short idxlen)

diff --git a/filter.c b/filter.c
index bd5c36d28f9c796e06a1ce63388f88f5ec91bbee..e1fcdf26a6c6057ff4056412135cf34b8587e703 100644 (file)
--- a/filter.c
+++ b/filter.c
@@ -30,10 +30,26 @@
 #include "protos.h"
 
 /**
- * mutt_create_filter_fd - Run a command on a pipe
+ * mutt_create_filter_fd - Run a command on a pipe (optionally connect stdin/stdout)
+ * @param cmd   Command line to invoke using `sh -c`
+ * @param in    File stream pointing to stdin for the command process, can be NULL
+ * @param out   File stream pointing to stdout for the command process, can be NULL
+ * @param err   File stream pointing to stderr for the command process, can be NULL
+ * @param fdin  If `in` is NULL and fdin is not -1 then fdin will be used as stdin for the command process
+ * @param fdout If `out` is NULL and fdout is not -1 then fdout will be used as stdout for the command process
+ * @param fderr If `error` is NULL and fderr is not -1 then fderr will be used as stderr for the command process
+ * @return Pid of the created process or -1 on any error creating pipes or forking
  *
- * Invokes a command on a pipe and optionally connects its stdin and stdout
- * to the specified handles.
+ * This function provides multiple mechanisms to handle IO sharing for the
+ * command process. File streams are prioritized over file descriptors if
+ * present.
+ *
+ * @code{.c}
+ *    mutt_create_filter_fd(commandline, NULL, NULL, NULL, -1, -1, -1);
+ * @endcode
+ *
+ * Additionally, in, out, and err will point to FILE* streams representing the
+ * processes stdin, stdout, and stderr.
  */
 pid_t mutt_create_filter_fd(const char *cmd, FILE **in, FILE **out, FILE **err,
                             int fdin, int fdout, int fderr)
@@ -183,6 +199,11 @@ pid_t mutt_create_filter(const char *s, FILE **in, FILE **out, FILE **err)
   return (mutt_create_filter_fd(s, in, out, err, -1, -1, -1));
 }
 
+/**
+ * mutt_wait_filter - Wait for the exit of a process and return its status
+ * @param pid Process id of the process to wait for
+ * @return Exit status of the process identified by pid or -1 in the event of an error
+ */
 int mutt_wait_filter(pid_t pid)
 {
   int rc;

diff --git a/muttlib.c b/muttlib.c
index b646d805a94667d7669d86f0cd5361de972fc3c3..0f2eca32fbb710bb88552aa4792d74f27f1ec60f 100644 (file)
--- a/muttlib.c
+++ b/muttlib.c
@@ -726,6 +726,7 @@ void mutt_delete_parameter(const char *attribute, struct Parameter **p)
 
 /**
  * mutt_needs_mailcap - Does this type need a mailcap entry do display
+ * @param m Attachment body to be displayed
  * @return
  * * true  Mutt requires a mailcap entry to display
  * * false otherwise

diff --git a/recvattach.c b/recvattach.c
index 37be1867f349c62695b66466834d720962fafc3f..073ae76815542b6b4704ef3c93be241ca0bc5105 100644 (file)
--- a/recvattach.c
+++ b/recvattach.c
@@ -404,6 +404,14 @@ int mutt_tag_attach(struct Menu *menu, int n, int m)
   return cur->tagged - ot;
 }
 
+/**
+ * mutt_is_message_type - Determine if a mime type matches a message or not
+ * @param type    Message type enum value
+ * @param subtype Message subtype
+ * @return
+ * * true  Type is message/news or message/rfc822
+ * * false Otherwise
+ */
 bool mutt_is_message_type(int type, const char *subtype)
 {
   if (type != TYPEMESSAGE)

diff --git a/rfc1524.c b/rfc1524.c
index 6c4cf0d54068d03cf5d3a8d7938442c1ff7daa3b..0882855bc8d6b0d00fa5126baf0b33a743601f06 100644 (file)
--- a/rfc1524.c
+++ b/rfc1524.c
@@ -353,11 +353,19 @@ static int rfc1524_mailcap_parse(struct Body *a, char *filename, char *type,
   return found;
 }
 
+/**
+ * rfc1524_new_entry - Allocate memory for a new rfc1524 entry
+ * @return Pointer to an un-initialized struct Rfc1524MailcapEntry
+ */
 struct Rfc1524MailcapEntry *rfc1524_new_entry(void)
 {
   return safe_calloc(1, sizeof(struct Rfc1524MailcapEntry));
 }
 
+/**
+ * rfc1524_free_entry - Deallocate an struct Rfc1524MailcapEntry
+ * @param entry Rfc1524MailcapEntry to deallocate.
+ */
 void rfc1524_free_entry(struct Rfc1524MailcapEntry **entry)
 {
   struct Rfc1524MailcapEntry *p = *entry;
@@ -374,10 +382,17 @@ void rfc1524_free_entry(struct Rfc1524MailcapEntry **entry)
 
 /**
  * rfc1524_mailcap_lookup - Find given type in the list of mailcap files
+ * @param a      Message body
+ * @param type   Text type in "type/subtype" format
+ * @param struct Rfc1524MailcapEntry pointer to an struct Rfc1524MailcapEntry to populate with results
+ * @param opt    Type of mailcap entry to lookup
+ * @return
+ * * 1 on success. If *entry is not NULL it poplates it with the mailcap entry
+ * * 0 if no matching entry is found
+ *
+ * opt can be one of: #MUTT_EDIT, #MUTT_COMPOSE, #MUTT_PRINT, #MUTT_AUTOVIEW
  *
- * On success, this returns the entry information in *entry, and returns 1.  On
- * failure (not found), returns 0.  If entry == NULL just return 1 if the given
- * type is found.
+ * Find the given type in the list of mailcap files.
  */
 int rfc1524_mailcap_lookup(struct Body *a, char *type,
                            struct Rfc1524MailcapEntry *entry, int opt)
@@ -436,21 +451,25 @@ static void strnfcpy(char *d, char *s, size_t siz, size_t len)
 }
 
 /**
- * rfc1524_expand_filename - Create temp filename match a template
+ * rfc1524_expand_filename - Expand a new filename from a template or existing filename
  * @param nametemplate Template
  * @param oldfile      Original filename
  * @param newfile      Buffer for new filename
  * @param nflen        Buffer length
  * @return
- * * 0 oldfile is fine as is
- * * 1 newfile specified
+ * * 0 if the left and right components of the oldfile and newfile match.
+ * * 1 otherwise.
+
+ * If there is no nametemplate, the stripped oldfile name is used as the
+ * template for newfile.
+ *
+ * If there is no oldfile, the stripped nametemplate name is used as the
+ * template for newfile.
  *
- * This routine will create a _temporary_ filename matching the
- * name template given if this needs to be done.
+ * If both a nametemplate and oldfile are specified, the template is checked
+ * for a "%s". If none is found, the nametemplate is used as the template for
+ * newfile.  The first path component of the nametemplate and oldfile are ignored.
  *
- * Please note that only the last path element of the
- * template and/or the old file name will be used for the
- * comparison and the temporary file name.
  */
 int rfc1524_expand_filename(char *nametemplate, char *oldfile, char *newfile, size_t nflen)
 {

diff --git a/sendlib.c b/sendlib.c
index 461e839161983f2786407da6ad7e97755d656f36..530c95b79a0f09429ee0157ab123a6dd416700f0 100644 (file)
--- a/sendlib.c
+++ b/sendlib.c
@@ -972,8 +972,8 @@ struct Content *mutt_get_content_info(const char *fname, struct Body *b)
  * @param path Path to attachment
  * @return MIME type, e.g. #TYPEIMAGE
  *
- * Given a file with path ``s'', see if there is a registered MIME type.
- * returns the major MIME type, and copies the subtype to ``d''.  First look
+ * Given a file at `path`, see if there is a registered MIME type.
+ * Returns the major MIME type, and copies the subtype to ``d''.  First look
  * for ~/.mime.types, then look in a system mime.types if we can find one.
  * The longest match is used so that we can match `ps.gz' when `gz' also
  * exists.