From: Richard Russon Date: Sat, 14 Jul 2018 14:54:04 +0000 (+0100) Subject: doxygen comment blocks X-Git-Tag: 2019-10-25~755^2~15 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=78f69f53429d4bc97aba9b8d95abe7a00c1a482b;p=neomutt doxygen comment blocks --- diff --git a/email/parse.c b/email/parse.c index 03be5acf6..08e6cd0f6 100644 --- a/email/parse.c +++ b/email/parse.c @@ -21,7 +21,7 @@ */ /** - * @page email_parse + * @page email_parse Miscellaneous email parsing routines * * Miscellaneous email parsing routines */ @@ -45,14 +45,21 @@ /** * mutt_matches_ignore - Does the string match the ignore list + * @param s String to check + * @retval true If string matches * - * checks Ignore and UnIgnore using mutt_list_match + * Checks Ignore and UnIgnore using mutt_list_match */ bool mutt_matches_ignore(const char *s) { return mutt_list_match(s, &Ignore) && !mutt_list_match(s, &UnIgnore); } +/** + * mutt_check_mime_type - Check a MIME type string + * @param s String to check + * @retval num MIME type, e.g. #TYPETEXT + */ int mutt_check_mime_type(const char *s) { if (mutt_str_strcasecmp("text", s) == 0) @@ -85,9 +92,13 @@ int mutt_check_mime_type(const char *s) /** * mutt_extract_message_id - Find a message-id + * @param s String to parse + * @param saveptr Save result here + * @retval ptr First character after message-id + * @retval NULL No more message ids * - * extract the first substring that looks like a message-id. - * call back with NULL for more (like strtok). + * Extract the first substring that looks like a message-id. + * Call back with NULL for more (like strtok). */ char *mutt_extract_message_id(const char *s, const char **saveptr) { @@ -149,6 +160,11 @@ char *mutt_extract_message_id(const char *s, const char **saveptr) return NULL; } +/** + * mutt_check_encoding - Check the encoding type + * @param c String to check + * @retval num Encoding type, e.g. #ENCQUOTEDPRINTABLE + */ int mutt_check_encoding(const char *c) { if (mutt_str_strncasecmp("7bit", c, sizeof("7bit") - 1) == 0) @@ -173,6 +189,11 @@ int mutt_check_encoding(const char *c) return ENCOTHER; } +/** + * parse_parameters - Parse a list of Parameters + * @param param Parameter list for the results + * @param s String to parse + */ static void parse_parameters(struct ParameterList *param, const char *s) { struct Parameter *new = NULL; @@ -290,6 +311,13 @@ bail: rfc2231_decode_parameters(param); } +/** + * parse_content_disposition - Parse a content disposition + * @param s String to parse + * @param ct Body to save the result + * + * e.g. parse a string "inline" and set #DISPINLINE. + */ static void parse_content_disposition(const char *s, struct Body *ct) { struct ParameterList parms; @@ -349,6 +377,13 @@ static void mutt_parse_content_language(char *s, struct Body *ct) ct->language = mutt_str_strdup(s); } +/** + * mutt_parse_content_type - Parse a content type + * @param s String to parse + * @param ct Body to save the result + * + * e.g. parse a string "inline" and set #DISPINLINE. + */ void mutt_parse_content_type(char *s, struct Body *ct) { FREE(&ct->subtype); @@ -439,6 +474,21 @@ void mutt_parse_content_type(char *s, struct Body *ct) } } +/** + * mutt_rfc822_parse_line - Parse an email header + * @param e Envelope of the email + * @param hdr Header of the email + * @param line Header field, e.g. 'to' + * @param p Header value, e.g. 'john@example.com' + * @param user_hdrs If true, save into the Envelope's userhdrs + * @param weed If true, perform header weeding (filtering) + * @param do_2047 If true, perform RFC2047 decoding of the field + * @retval 1 If the field is recognised + * @retval 0 If not + * + * Process a line from an email header. Each line that is recognised is parsed + * and the information put in the Envelope or Header. + */ int mutt_rfc822_parse_line(struct Envelope *e, struct Header *hdr, char *line, char *p, short user_hdrs, short weed, short do_2047) { @@ -581,10 +631,9 @@ int mutt_rfc822_parse_line(struct Envelope *e, struct Header *hdr, char *line, { if (hdr) { - /* - * HACK - neomutt has, for a very short time, produced negative - * Lines header values. Ignore them. - */ + /* HACK - neomutt has, for a very short time, produced negative + * Lines header values. Ignore them. + */ if (mutt_str_atoi(p, &hdr->lines) < 0 || hdr->lines < 0) hdr->lines = 0; } @@ -825,6 +874,10 @@ int mutt_rfc822_parse_line(struct Envelope *e, struct Header *hdr, char *line, /** * mutt_rfc822_read_line - Read a header line from a file + * @param f File to read from + * @param line Buffer to store the result + * @param linelen Length of buffer + * @retval ptr Line read from file * * Reads an arbitrarily long header field, and looks ahead for continuation * lines. ``line'' must point to a dynamically allocated string; it is @@ -1154,6 +1207,11 @@ bool mutt_is_message_type(int type, const char *subtype) (mutt_str_strcasecmp(subtype, "news") == 0)); } +/** + * mutt_parse_part - Parse a MIME part + * @param fp File to read from + * @param b Body to store the results in + */ void mutt_parse_part(FILE *fp, struct Body *b) { char *bound = NULL; @@ -1267,9 +1325,7 @@ struct Body *mutt_parse_multipart(FILE *fp, const char *boundary, LOFF_T end_off break; } #endif - - /* - * Consistency checking - catch + /* Consistency checking - catch * bad attachment end boundaries */ diff --git a/email/rfc2231.c b/email/rfc2231.c index c5325b841..52ad88a2b 100644 --- a/email/rfc2231.c +++ b/email/rfc2231.c @@ -20,8 +20,13 @@ * this program. If not, see . */ -/* Yet another MIME encoding for header data. This time, it's parameters, - * specified in RFC2231, and modeled after the encoding used in URLs. +/** + * @page email_rfc2231 RFC2231 MIME Charset routines + * + * RFC2231 MIME Charset routines + * + * Yet another MIME encoding for header data. This time, it's parameters, + * specified in RFC2231, and modelled after the encoding used in URLs. * * Additionally, continuations and encoding are mixed in an, errrm, interesting * manner. @@ -54,6 +59,10 @@ struct Rfc2231Parameter struct Rfc2231Parameter *next; }; +/** + * purge_empty_parameters - Remove any ill-formed Parameters from a list + * @param p Parameter List to check + */ static void purge_empty_parameters(struct ParameterList *p) { struct Parameter *np, *tmp; @@ -67,6 +76,13 @@ static void purge_empty_parameters(struct ParameterList *p) } } +/** + * rfc2231_get_charset - Get the charset from an RFC2231 header + * @param value Header string + * @param charset Buffer for the result + * @param chslen Length of buffer + * @retval ptr First character after charset + */ static char *rfc2231_get_charset(char *value, char *charset, size_t chslen) { char *t = strchr(value, '\''); @@ -86,6 +102,11 @@ static char *rfc2231_get_charset(char *value, char *charset, size_t chslen) return (t + 1); } +/** + * rfc2231_decode_one - Decode one percent-encoded character + * @param[out] dest Where to save the result + * @param[in] src Source string + */ static void rfc2231_decode_one(char *dest, char *src) { char *d = NULL; @@ -105,13 +126,19 @@ static void rfc2231_decode_one(char *dest, char *src) *d = '\0'; } +/** + * rfc2231_new_parameter - Create a new Rfc2231Parameter + * @retval ptr Newly allocated Rfc2231Parameter + */ static struct Rfc2231Parameter *rfc2231_new_parameter(void) { return mutt_mem_calloc(1, sizeof(struct Rfc2231Parameter)); } /** - * rfc2231_list_insert - insert parameter into an ordered list + * rfc2231_list_insert - Insert parameter into an ordered list + * @param list List to insert into + * @param par Paramter to insert * * Primary sorting key: attribute * Secondary sorting key: index @@ -135,6 +162,10 @@ static void rfc2231_list_insert(struct Rfc2231Parameter **list, struct Rfc2231Pa *last = par; } +/** + * rfc2231_free_parameter - Free an Rfc2231Parameter + * @param p Rfc2231Parameter to free + */ static void rfc2231_free_parameter(struct Rfc2231Parameter **p) { if (*p) @@ -146,7 +177,9 @@ static void rfc2231_free_parameter(struct Rfc2231Parameter **p) } /** - * rfc2231_join_continuations - process continuation parameters + * rfc2231_join_continuations - Process continuation parameters + * @param p Parameter List for the results + * @param par Continuation Parameter */ static void rfc2231_join_continuations(struct ParameterList *p, struct Rfc2231Parameter *par) { @@ -195,6 +228,10 @@ static void rfc2231_join_continuations(struct ParameterList *p, struct Rfc2231Pa } } +/** + * rfc2231_decode_parameters - Decode a Parameter list + * @param p List to decode + */ void rfc2231_decode_parameters(struct ParameterList *p) { struct Rfc2231Parameter *conthead = NULL; @@ -276,17 +313,22 @@ void rfc2231_decode_parameters(struct ParameterList *p) purge_empty_parameters(p); } +/** + * rfc2231_encode_string - Encode a string to be suitable for an RFC2231 header + * @param pd String to encode + * @retval 1 If string was encoded + * @retval 0 If no + * + * The string is encoded in-place. + */ int rfc2231_encode_string(char **pd) { int ext = 0, encode = 0; char *charset = NULL, *s = NULL, *t = NULL, *e = NULL, *d = NULL; size_t slen, dlen = 0; - /* - * A shortcut to detect pure 7bit data. - * - * This should prevent the worst when character set handling - * is flawed. + /* A shortcut to detect pure 7bit data. + * This should prevent the worst when character set handling is flawed. */ for (s = *pd; *s; s++) diff --git a/email/url.c b/email/url.c index 200d12298..422bc49ef 100644 --- a/email/url.c +++ b/email/url.c @@ -34,6 +34,9 @@ #include "url.h" #include "mime.h" +/** + * UrlMap - Constants for URL protocols, e.g. 'imap://' + */ static const struct Mapping UrlMap[] = { { "file", U_FILE }, { "imap", U_IMAP }, { "imaps", U_IMAPS }, { "pop", U_POP }, { "pops", U_POPS }, { "news", U_NNTP }, @@ -41,6 +44,15 @@ static const struct Mapping UrlMap[] = { { "smtp", U_SMTP }, { "smtps", U_SMTPS }, { NULL, U_UNKNOWN }, }; +/** + * url_pct_decode - Decode a percent-encoded string + * @param s String to decode + * @retval 0 Success + * @retval -1 Error + * + * e.g. turn "hello%20world" into "hello world" + * The string is decoded in-place. + */ int url_pct_decode(char *s) { char *d = NULL; @@ -68,6 +80,11 @@ int url_pct_decode(char *s) return 0; } +/** + * url_check_scheme - Check the protocol of a URL + * @param s String to check + * @retval num Url type, e.g. #U_IMAPS + */ enum UrlScheme url_check_scheme(const char *s) { char sbuf[STRING]; @@ -90,6 +107,13 @@ enum UrlScheme url_check_scheme(const char *s) return (enum UrlScheme) i; } +/** + * parse_query_string - Parse a URL query string + * @param u Url to store the results + * @param src String to parse + * @retval 0 Success + * @retval -1 Error + */ static int parse_query_string(struct Url *u, char *src) { struct UrlQueryString *qs = NULL; @@ -253,6 +277,12 @@ err: return -1; } +/** + * url_free - Free the contents of a URL + * @param u Url to empty + * + * @note The Url itself is not freed + */ void url_free(struct Url *u) { struct UrlQueryString *np = STAILQ_FIRST(&u->query_strings), *next = NULL; @@ -267,6 +297,14 @@ void url_free(struct Url *u) STAILQ_INIT(&u->query_strings); } +/** + * url_pct_encode - Percent-encode a string + * @param dst Buffer for the result + * @param l Length of buffer + * @param src String to encode + * + * e.g. turn "hello world" into "hello%20world" + */ void url_pct_encode(char *dst, size_t l, const char *src) { static const char *alph = "0123456789ABCDEF"; @@ -294,7 +332,13 @@ void url_pct_encode(char *dst, size_t l, const char *src) } /** - * url_tostring - output the URL string for a given Url object + * url_tostring - Output the URL string for a given Url object + * @param u Url to turn into a string + * @param dest Buffer for the result + * @param len Length of buffer + * @param flags Flags, e.g. #U_DECODE_PASSWD + * @retval 0 Success + * @retval -1 Error */ int url_tostring(struct Url *u, char *dest, size_t len, int flags) {