comments

diff --git a/webcit/auth.c b/webcit/auth.c
index 8ab372093d752e207d323f4118025ae161134f97..5c800aa3b423e0e1e600bf755e477435ed5b1f4c 100644 (file)
--- 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 3c3770e508deeb128392a0dcb1e0263072563afc..b4657c9b5bbbd4e7a74877869cd3ed68ed411292 100644 (file)
--- 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 b2b18c8a24bb0e56c5fb0eb6f2a30bae12438605..8ac59b8252af978235603855cac70c4949f62263 100644 (file)
--- 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,