From: Steven! Ragnarök Date: Tue, 18 Jul 2017 13:59:46 +0000 (+0100) Subject: docs: document some functions X-Git-Tag: neomutt-20170907~64 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=db47b5ca3283704cf7dd23514edd1c90c33e89c2;p=neomutt docs: document some functions --- diff --git a/attach.c b/attach.c index 4d865bcfb..e722b9d29 100644 --- 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 bd5c36d28..e1fcdf26a 100644 --- 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 b646d805a..0f2eca32f 100644 --- 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 37be1867f..073ae7681 100644 --- 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 6c4cf0d54..0882855bc 100644 --- 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 461e83916..530c95b79 100644 --- 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.