From 48b0267c4d38cc74171a78927398d4c00b3f89fa Mon Sep 17 00:00:00 2001 From: Art Cancro Date: Fri, 27 Jan 2006 23:17:02 +0000 Subject: [PATCH] comments --- webcit/auth.c | 3 +- webcit/messages.c | 83 ++++++++++++++++++++++++++++------------------- webcit/webcit.c | 35 +++++++++++--------- 3 files changed, 70 insertions(+), 51 deletions(-) diff --git a/webcit/auth.c b/webcit/auth.c index 8ab372093..5c800aa3b 100644 --- a/webcit/auth.c +++ b/webcit/auth.c @@ -90,9 +90,10 @@ void display_login(char *mesg) * by a timed-out session automatically re-establishing with a little help * from the browser cookie. Either way, we need to load access controls and * preferences from the server. + * * \param user the username * \param pass his password - * \param serv_response where to put the response ???? + * \param serv_response The parameters returned from a Citadel USER or NEWU command */ void become_logged_in(char *user, char *pass, char *serv_response) { diff --git a/webcit/messages.c b/webcit/messages.c index 3c3770e50..b4657c9b5 100644 --- a/webcit/messages.c +++ b/webcit/messages.c @@ -11,9 +11,9 @@ #include "webserver.h" #include "groupdav.h" -#define SUBJ_COL_WIDTH_PCT 50 /**< ??? */ -#define SENDER_COL_WIDTH_PCT 30 /**< ??? */ -#define DATE_PLUS_BUTTONS_WIDTH_PCT 20 /**< ??? */ +#define SUBJ_COL_WIDTH_PCT 50 /**< Mailbox view column width */ +#define SENDER_COL_WIDTH_PCT 30 /**< Mailbox view column width */ +#define DATE_PLUS_BUTTONS_WIDTH_PCT 20 /**< Mailbox view column width */ /** * Address book entry (keep it short and sweet, it's just a quickie lookup @@ -21,7 +21,7 @@ */ struct addrbookent { char ab_name[64]; /**< name string */ - long ab_msgnum; /**< number in the citadel???? */ + long ab_msgnum; /**< message number of address book entry */ }; @@ -1025,7 +1025,8 @@ ENDBODY: /** * \brief Unadorned HTML output of an individual message, suitable * for placing in a hidden iframe, for printing, or whatever - * \param msgnum_as_string the message to embed??? + * + * \param msgnum_as_string Message number, as a string instead of as a long int */ void embed_message(char *msgnum_as_string) { long msgnum = 0L; @@ -1039,7 +1040,8 @@ void embed_message(char *msgnum_as_string) { /** * \brief Printable view of a message - * \param msgnum_as_string the message to print??? + * + * \param msgnum_as_string Message number, as a string instead of as a long int */ void print_message(char *msgnum_as_string) { long msgnum = 0L; @@ -1068,7 +1070,8 @@ void print_message(char *msgnum_as_string) { /** * \brief Display a message's headers - * \param msgnum_as_string the message headers to print??? + * + * \param msgnum_as_string Message number, as a string instead of as a long int */ void display_headers(char *msgnum_as_string) { long msgnum = 0L; @@ -1098,13 +1101,14 @@ void display_headers(char *msgnum_as_string) { /** * \brief Read message in simple, JavaScript-embeddable form for 'forward' - * or 'reply quoted' operations. + * or 'reply quoted' operations. * * NOTE: it is VITALLY IMPORTANT that we output no single-quotes or linebreaks * in this function. Doing so would throw a JavaScript error in the * 'supplied text' argument to the editor. - * \param msgnum the citadel message number - * \param forward_attachments atachment to forward??? + * + * \param msgnum Message number of the message we want to quote + * \param forward_attachments Nonzero if we want attachments to be forwarded */ void pullquote_message(long msgnum, int forward_attachments, int include_headers) { char buf[SIZ]; @@ -1405,8 +1409,9 @@ ENDBODY: } /** - * \brief display sumarized item??? - * \param num hom many? which??? + * \brief Display one row in the mailbox summary view + * + * \param num The row number to be displayed */ void display_summarized(int num) { char datebuf[64]; @@ -1805,9 +1810,10 @@ int load_msg_ptrs(char *servcmd, int with_headers) } /** - * \brief compare what???? - * \param s1 first thing to compare - * \param s2 second thing to compare + * \brief qsort() compatible function to compare two longs in descending order. + * + * \param s1 first number to compare + * \param s2 second number to compare */ int longcmp_r(const void *s1, const void *s2) { long l1; @@ -1823,9 +1829,10 @@ int longcmp_r(const void *s1, const void *s2) { /** - * \brief compare what???? - * \param s1 first thing to compare - * \param s2 second thing to compare + * \brief qsort() compatible function to compare two message summary structs by ascending subject. + * + * \param s1 first item to compare + * \param s2 second item to compare */ int summcmp_subj(const void *s1, const void *s2) { struct message_summary *summ1; @@ -1837,9 +1844,10 @@ int summcmp_subj(const void *s1, const void *s2) { } /** - * \brief compare what???? - * \param s1 first thing to compare - * \param s2 second thing to compare + * \brief qsort() compatible function to compare two message summary structs by descending subject. + * + * \param s1 first item to compare + * \param s2 second item to compare */ int summcmp_rsubj(const void *s1, const void *s2) { struct message_summary *summ1; @@ -1851,9 +1859,10 @@ int summcmp_rsubj(const void *s1, const void *s2) { } /** - * \brief compare what???? - * \param s1 first thing to compare - * \param s2 second thing to compare + * \brief qsort() compatible function to compare two message summary structs by ascending sender. + * + * \param s1 first item to compare + * \param s2 second item to compare */ int summcmp_sender(const void *s1, const void *s2) { struct message_summary *summ1; @@ -1865,9 +1874,10 @@ int summcmp_sender(const void *s1, const void *s2) { } /** - * \brief compare what???? - * \param s1 first thing to compare - * \param s2 second thing to compare + * \brief qsort() compatible function to compare two message summary structs by descending sender. + * + * \param s1 first item to compare + * \param s2 second item to compare */ int summcmp_rsender(const void *s1, const void *s2) { struct message_summary *summ1; @@ -1879,9 +1889,10 @@ int summcmp_rsender(const void *s1, const void *s2) { } /** - * \brief compare what???? - * \param s1 first thing to compare - * \param s2 second thing to compare + * \brief qsort() compatible function to compare two message summary structs by ascending date. + * + * \param s1 first item to compare + * \param s2 second item to compare */ int summcmp_date(const void *s1, const void *s2) { struct message_summary *summ1; @@ -1896,9 +1907,10 @@ int summcmp_date(const void *s1, const void *s2) { } /** - * \brief compare what???? - * \param s1 first thing to compare - * \param s2 second thing to compare + * \brief qsort() compatible function to compare two message summary structs by descending date. + * + * \param s1 first item to compare + * \param s2 second item to compare */ int summcmp_rdate(const void *s1, const void *s2) { struct message_summary *summ1; @@ -1912,9 +1924,12 @@ int summcmp_rdate(const void *s1, const void *s2) { else return 0; } + + /** * \brief command loop for reading messages - * \param oper what??? + * + * \param oper Set to "readnew" or "readold" or "readfwd" or "headers" */ void readloop(char *oper) { diff --git a/webcit/webcit.c b/webcit/webcit.c index b2b18c8a2..8ac59b825 100644 --- a/webcit/webcit.c +++ b/webcit/webcit.c @@ -142,7 +142,7 @@ void dump_vars(void) /** * \brief Return the value of a variable supplied to the current web page (from the url or a form) - * \param key what??? + * \param key The name of the variable we want */ char *bstr(char *key) { @@ -196,8 +196,8 @@ void wDumpContent(int print_standard_html_footer) /** * \brief Copy a string, escaping characters which have meaning in HTML. - * \param target target buffer to copy to - * \param strbuf source buffer ??? + * \param target target buffer + * \param strbuf source buffer * \param nbsp If nonzero, spaces are converted to non-breaking spaces. * \param nolinebreaks if set, linebreaks are removed from the string. */ @@ -263,8 +263,8 @@ void escputs(char *strbuf) /** * \brief Escape a string for feeding out as a URL. * Returns a pointer to a buffer that must be freed by the caller! - * \param outbuf the outputbuffer - * \param strbuf the input buffer??? + * \param outbuf the output buffer + * \param strbuf the input buffer */ void urlesc(char *outbuf, char *strbuf) { @@ -823,17 +823,20 @@ void authorization_required(const char *message) } /** - * \brief handle file uploads - * \param name the url the upload is done to - * \param filename the name of the file being uploaded - * \param partnum item number on the citadel server ??? - * \param disp what??? - * \param content the file contents??? - * \param cbtype what??? - * \param cbcharset the character set of cb?? - * \param length the size of the file ??? - * \param encoding charset encoding of the file?? - * \param userdata what??? + * \brief This function is called by the MIME parser to handle data uploaded by + * the browser. Form data, uploaded files, and the data from HTTP PUT + * operations (such as those found in GroupDAV) all arrive this way. + * + * \param name Name of the item being uploaded + * \param filename Filename of the item being uploaded + * \param partnum MIME part identifier (not needed) + * \param disp MIME content disposition (not needed) + * \param content The actual data + * \param cbtype MIME content-type + * \param cbcharset Character set + * \param length Content length + * \param encoding MIME encoding type (not needed) + * \param userdata Not used here */ void upload_handler(char *name, char *filename, char *partnum, char *disp, void *content, char *cbtype, char *cbcharset, -- 2.39.2