Doxy corrections, fixes, and sync

15 files changed, 64 insertions, 36 deletions

diff --git a/src/include/microhttpd.h b/src/include/microhttpd.h
index 24bb8839..811b2fc0 100644
--- a/src/include/microhttpd.h
+++ b/src/include/microhttpd.h
@@ -2412,6 +2412,7 @@ typedef enum MHD_Result
  *
  * @param cls argument given together with the function
  *        pointer when the handler was registered with MHD
+ * @param connection the connection handle
  * @param url the requested url
  * @param method the HTTP method used (#MHD_HTTP_METHOD_GET,
  *        #MHD_HTTP_METHOD_PUT, etc.)
@@ -4243,12 +4244,12 @@ MHD_queue_auth_fail_response2 (struct MHD_Connection *connection,
 
 
 /**
- * Queues a response to request authentication from the client
+ * Queues a response to request authentication from the client.
  * For now uses MD5 (for backwards-compatibility). Still, if you
- * need to be sure, use #MHD_queue_fail_auth_response2().
+ * need to be sure, use #MHD_queue_auth_fail_response2().
  *
  * @param connection The MHD connection structure
- * @param realm The realm presented to the client
+ * @param realm the realm presented to the client
  * @param opaque string to user for opaque value
  * @param response reply to send; should contain the "access denied"
  *        body; note that this function will set the "WWW Authenticate"
diff --git a/src/microhttpd/connection.c b/src/microhttpd/connection.c
index 84bfc662..2490a1fb 100644
--- a/src/microhttpd/connection.c
+++ b/src/microhttpd/connection.c
@@ -1757,7 +1757,6 @@ is_reply_body_needed (struct MHD_Connection *connection)
  * type and other.
  *
  * @param connection to connection to process
- * @param reply_body_allowed
  */
 static void
 setup_reply_properties (struct MHD_Connection *connection)
@@ -3844,7 +3843,9 @@ MHD_connection_handle_read (struct MHD_Connection *connection,
 
 /**
  * This function was created to handle writes to sockets when it has
- * been determined that the socket can be written to.
+ * been determined that the socket can be written to. All
+ * implementations (multithreaded, external select, internal select)
+ * call this function
  *
  * @param connection connection to handle
  */
@@ -4400,6 +4401,8 @@ connection_reset (struct MHD_Connection *connection,
 /**
  * This function was created to handle per-connection processing that
  * has to happen even if the socket cannot be read or written to.
+ * All implementations (multithreaded, external select, internal select)
+ * call this function.
  * @remark To be called only from thread that process connection's
  * recv(), send() and response.
  *
diff --git a/src/microhttpd/connection.h b/src/microhttpd/connection.h
index 50816ce2..9f1a0ffb 100644
--- a/src/microhttpd/connection.h
+++ b/src/microhttpd/connection.h
@@ -114,8 +114,8 @@ MHD_connection_handle_write (struct MHD_Connection *connection);
 
 /**
  * This function was created to handle per-connection processing that
- * has to happen even if the socket cannot be read or written to.  All
- * implementations (multithreaded, external select, internal select)
+ * has to happen even if the socket cannot be read or written to.
+ * All implementations (multithreaded, external select, internal select)
  * call this function.
  * @remark To be called only from thread that process connection's
  * recv(), send() and response.
diff --git a/src/microhttpd/daemon.c b/src/microhttpd/daemon.c
index 5ca612ea..1ddbd83e 100644
--- a/src/microhttpd/daemon.c
+++ b/src/microhttpd/daemon.c
@@ -90,7 +90,7 @@
 
 /**
  * Close all connections for the daemon.
- * Must only be called when MHD_Daemon::shutdown was set to #MHD_YES.
+ * Must only be called when MHD_Daemon::shutdown was set to true.
  * @remark To be called only from thread that process
  * daemon's select()/poll()/etc.
  *
@@ -240,6 +240,7 @@ MHD_default_logger_ (void *cls,
  * Free the memory given by @a ptr. Calls "free(ptr)".  This function
  * should be used to free the username returned by
  * #MHD_digest_auth_get_username().
+ * @note Available since #MHD_VERSION 0x00095600
  *
  * @param ptr pointer to free.
  */
@@ -3235,9 +3236,15 @@ MHD_suspend_connection (struct MHD_Connection *connection)
 
 /**
  * Resume handling of network data for suspended connection.  It is
- * safe to resume a suspended connection at any time.  Calling this function
- * on a connection that was not previously suspended will result
- * in undefined behavior.
+ * safe to resume a suspended connection at any time.  Calling this
+ * function on a connection that was not previously suspended will
+ * result in undefined behavior.
+ *
+ * If you are using this function in "external" sockets polling mode, you must
+ * make sure to run #MHD_run() and #MHD_get_timeout() afterwards (before
+ * again calling #MHD_get_fdset()), as otherwise the change may not be
+ * reflected in the set returned by #MHD_get_fdset() and you may end up
+ * with a connection that is stuck until the next network activity.
  *
  * @param connection the connection to resume
  */
diff --git a/src/microhttpd/digestauth.c b/src/microhttpd/digestauth.c
index aaed170e..2d70e10a 100644
--- a/src/microhttpd/digestauth.c
+++ b/src/microhttpd/digestauth.c
@@ -81,7 +81,7 @@
 #endif
 
 /**
- * Check that @a n is below #MAX_NONCE
+ * Check that @a n is below #MAX_DIGEST
  */
 #define VLA_CHECK_LEN_DIGEST(n) do { if ((n) > MAX_DIGEST) mhd_panic ( \
                                        mhd_panic_cls, __FILE__, __LINE__, \
@@ -205,7 +205,7 @@ cvthex (const unsigned char *bin,
  *          da->sessionkey will be initialized to the digest in HEX
  * @param digest An `unsigned char *' pointer to the binary MD5 sum
  *      for the precalculated hash value "username:realm:password"
- *      of #MHD_MD5_DIGEST_SIZE or #MHD_SHA256_DIGEST_SIZE bytes
+ *      of #MHD_MD5_DIGEST_SIZE or #SHA256_DIGEST_SIZE bytes
  * @param nonce A `char *' pointer to the nonce value
  * @param cnonce A `char *' pointer to the cnonce value
  */
@@ -1457,7 +1457,7 @@ MHD_queue_auth_fail_response2 (struct MHD_Connection *connection,
 /**
  * Queues a response to request authentication from the client.
  * For now uses MD5 (for backwards-compatibility). Still, if you
- * need to be sure, use #MHD_queue_fail_auth_response2().
+ * need to be sure, use #MHD_queue_auth_fail_response2().
  *
  * @param connection The MHD connection structure
  * @param realm the realm presented to the client
@@ -1469,6 +1469,7 @@ MHD_queue_auth_fail_response2 (struct MHD_Connection *connection,
  *      'stale=true' to the authentication header
  * @return #MHD_YES on success, #MHD_NO otherwise
  * @ingroup authentication
+ * @deprecated use MHD_queue_auth_fail_response2()
  */
 enum MHD_Result
 MHD_queue_auth_fail_response (struct MHD_Connection *connection,
diff --git a/src/microhttpd/internal.c b/src/microhttpd/internal.c
index dacb433f..055deb32 100644
--- a/src/microhttpd/internal.c
+++ b/src/microhttpd/internal.c
@@ -139,7 +139,7 @@ MHD_unescape_plus (char *arg)
  * The result must also still be 0-terminated.
  *
  * @param val value to unescape (modified in the process)
- * @return length of the resulting val (strlen(val) maybe
+ * @return length of the resulting val (`strlen(val)` may be
  *  shorter afterwards due to elimination of escape sequences)
  */
 size_t
diff --git a/src/microhttpd/internal.h b/src/microhttpd/internal.h
index 45c17441..3c1a889d 100644
--- a/src/microhttpd/internal.h
+++ b/src/microhttpd/internal.h
@@ -414,7 +414,7 @@ struct MHD_iovec_track_
   MHD_iovec_ *iov;
 
   /**
-   * The number of elements in @iov.
+   * The number of elements in @a iov.
    * This value is not changed during lifetime.
    */
   size_t cnt;
diff --git a/src/microhttpd/md5.c b/src/microhttpd/md5.c
index 4de888a8..d267e803 100644
--- a/src/microhttpd/md5.c
+++ b/src/microhttpd/md5.c
@@ -37,7 +37,7 @@
  * Start MD5 accumulation.  Set bit count to 0 and buffer to mysterious
  * initialization constants.
  *
- * @param ctx must be a `struct MD5Context *`
+ * @param ctx_ must be a `struct MD5Context *`
  */
 void
 MHD_MD5Init (void *ctx_)
@@ -59,9 +59,9 @@ MD5Transform (uint32_t state[4],
 
 
 /**
- * Final wrapup, fill in digest and zero out ctx.
+ * Final wrapup--call MD5Pad, fill in digest and zero out ctx.
  *
- * @param ctx must be a `struct MD5Context *`
+ * @param ctx_ must be a `struct MD5Context *`
  */
 void
 MHD_MD5Final (void *ctx_,
@@ -264,6 +264,10 @@ MD5Transform (uint32_t state[4],
 /**
  * Update context to reflect the concatenation of another buffer full
  * of bytes.
+ *
+ * @param ctx_ must be a `struct MD5Context *`
+ * @param input bytes to add to hash
+ * @param len the number of bytes in @a data
  */
 void
 MHD_MD5Update (void *ctx_,
diff --git a/src/microhttpd/md5.h b/src/microhttpd/md5.h
index 14cee305..239cf664 100644
--- a/src/microhttpd/md5.h
+++ b/src/microhttpd/md5.h
@@ -51,6 +51,8 @@ MHD_MD5Init (void *ctx_);
  * of bytes.
  *
  * @param ctx_ must be a `struct MD5Context *`
+ * @param input bytes to add to hash
+ * @param len the number of bytes in @a data
  */
 void
 MHD_MD5Update (void *ctx_,
diff --git a/src/microhttpd/memorypool.c b/src/microhttpd/memorypool.c
index 58fc1e45..49ed9524 100644
--- a/src/microhttpd/memorypool.c
+++ b/src/microhttpd/memorypool.c
@@ -499,7 +499,7 @@ MHD_pool_reallocate (struct MemoryPool *pool,
 
 /**
  * Clear all entries from the memory pool except
- * for @a keep of the given @a size. The pointer
+ * for @a keep of the given @a copy_bytes.  The pointer
  * returned should be a buffer of @a new_size where
  * the first @a copy_bytes are from @a keep.
  *
diff --git a/src/microhttpd/memorypool.h b/src/microhttpd/memorypool.h
index ab977d12..98f96bda 100644
--- a/src/microhttpd/memorypool.h
+++ b/src/microhttpd/memorypool.h
@@ -92,7 +92,7 @@ MHD_pool_allocate (struct MemoryPool *pool,
  * Try to allocate @a size bytes memory area from the @a pool.
  *
  * If allocation fails, @a required_bytes is updated with size required to be
- * freed in the @a pool from relocatable area to allocate requested number
+ * freed in the @a pool from rellocatable area to allocate requested number
  * of bytes.
  * Allocated memory area is always not rellocatable ("from end").
  *
@@ -104,7 +104,7 @@ MHD_pool_allocate (struct MemoryPool *pool,
  *                            Cannot be NULL.
  * @return the pointer to allocated memory area if succeed,
  *         NULL if the pool doesn't have enough space, required_bytes is updated
- *         with amount of space needed to be freed in relocatable area or
+ *         with amount of space needed to be freed in rellocatable area or
  *         set to SIZE_MAX if requested size is too large for the pool.
  */
 void *
diff --git a/src/microhttpd/mhd_str.c b/src/microhttpd/mhd_str.c
index 6c07a574..7c7fcf1f 100644
--- a/src/microhttpd/mhd_str.c
+++ b/src/microhttpd/mhd_str.c
@@ -226,7 +226,7 @@ toxdigitvalue (char c)
  * Caseless compare two characters.
  *
  * @param c1 the first char to compare
- * @param c1 the second char to compare
+ * @param c2 the second char to compare
  * @return boolean 'true' if chars are caseless equal, false otherwise
  */
 _MHD_static_inline bool
@@ -356,7 +356,7 @@ charsequalcaseless (const char c1, const char c2)
  * Caseless compare two characters.
  *
  * @param c1 the first char to compare
- * @param c1 the second char to compare
+ * @param c2 the second char to compare
  * @return boolean 'true' if chars are caseless equal, false otherwise
  */
 #define charsequalcaseless(c1, c2) \
diff --git a/src/microhttpd/mhd_str.h b/src/microhttpd/mhd_str.h
index 4faeba08..2943cf27 100644
--- a/src/microhttpd/mhd_str.h
+++ b/src/microhttpd/mhd_str.h
@@ -74,6 +74,7 @@ struct _MHD_str_w_len
 #ifndef MHD_FAVOR_SMALL_CODE
 /**
  * Check two strings for equality, ignoring case of US-ASCII letters.
+ *
  * @param str1 first string to compare
  * @param str2 second string to compare
  * @return non-zero if two strings are equal, zero otherwise.
@@ -123,7 +124,7 @@ MHD_str_equal_caseless_bin_n_ (const char *const str1,
 /**
  * Check whether @a str has case-insensitive @a token.
  * Token could be surrounded by spaces and tabs and delimited by comma.
- * Match succeed if substring between start, end of string or comma
+ * Match succeed if substring between start, end (of string) or comma
  * contains only case-insensitive token and optional spaces and tabs.
  * @warning token must not contain null-characters except optional
  *          terminating null-character.
@@ -225,8 +226,9 @@ MHD_str_remove_tokens_caseless_ (char *str,
 /**
  * Convert decimal US-ASCII digits in string to number in uint64_t.
  * Conversion stopped at first non-digit character.
+ *
  * @param str string to convert
- * @param out_val pointer to uint64_t to store result of conversion
+ * @param[out] out_val pointer to uint64_t to store result of conversion
  * @return non-zero number of characters processed on succeed,
  *         zero if no digit is found, resulting value is larger
  *         then possible to store in uint64_t or @a out_val is NULL
@@ -240,9 +242,10 @@ MHD_str_to_uint64_ (const char *str,
  * number in uint64_t.
  * Conversion stopped at first non-digit character or after @a maxlen
  * digits.
+ *
  * @param str string to convert
  * @param maxlen maximum number of characters to process
- * @param out_val pointer to uint64_t to store result of conversion
+ * @param[out] out_val pointer to uint64_t to store result of conversion
  * @return non-zero number of characters processed on succeed,
  *         zero if no digit is found, resulting value is larger
  *         then possible to store in uint64_t or @a out_val is NULL
@@ -256,8 +259,9 @@ MHD_str_to_uint64_n_ (const char *str,
 /**
  * Convert hexadecimal US-ASCII digits in string to number in uint32_t.
  * Conversion stopped at first non-digit character.
+ *
  * @param str string to convert
- * @param out_val pointer to uint32_t to store result of conversion
+ * @param[out] out_val pointer to uint32_t to store result of conversion
  * @return non-zero number of characters processed on succeed,
  *         zero if no digit is found, resulting value is larger
  *         then possible to store in uint32_t or @a out_val is NULL
@@ -272,9 +276,10 @@ MHD_strx_to_uint32_ (const char *str,
  * to number in uint32_t.
  * Conversion stopped at first non-digit character or after @a maxlen
  * digits.
+ *
  * @param str string to convert
  * @param maxlen maximum number of characters to process
- * @param out_val pointer to uint32_t to store result of conversion
+ * @param[out] out_val pointer to uint32_t to store result of conversion
  * @return non-zero number of characters processed on succeed,
  *         zero if no digit is found, resulting value is larger
  *         then possible to store in uint32_t or @a out_val is NULL
@@ -288,8 +293,9 @@ MHD_strx_to_uint32_n_ (const char *str,
 /**
  * Convert hexadecimal US-ASCII digits in string to number in uint64_t.
  * Conversion stopped at first non-digit character.
+ *
  * @param str string to convert
- * @param out_val pointer to uint64_t to store result of conversion
+ * @param[out] out_val pointer to uint64_t to store result of conversion
  * @return non-zero number of characters processed on succeed,
  *         zero if no digit is found, resulting value is larger
  *         then possible to store in uint64_t or @a out_val is NULL
@@ -304,9 +310,10 @@ MHD_strx_to_uint64_ (const char *str,
  * to number in uint64_t.
  * Conversion stopped at first non-digit character or after @a maxlen
  * digits.
+ *
  * @param str string to convert
  * @param maxlen maximum number of characters to process
- * @param out_val pointer to uint64_t to store result of conversion
+ * @param[out] out_val pointer to uint64_t to store result of conversion
  * @return non-zero number of characters processed on succeed,
  *         zero if no digit is found, resulting value is larger
  *         then possible to store in uint64_t or @a out_val is NULL
@@ -325,15 +332,16 @@ MHD_strx_to_uint64_n_ (const char *str,
  * Conversion stopped at first non-digit character or after @a maxlen
  * digits.
  * To be used only within macro.
+ *
  * @param str the string to convert
  * @param maxlen the maximum number of characters to process
- * @param out_val the pointer to uint64_t to store result of conversion
- * @param val_size the size of variable pointed by @a out_val
+ * @param out_val the pointer to variable to store result of conversion
+ * @param val_size the size of variable pointed by @a out_val, in bytes, 4 or 8
  * @param max_val the maximum decoded number
  * @param base the numeric base, 10 or 16
  * @return non-zero number of characters processed on succeed,
  *         zero if no digit is found, resulting value is larger
- *         then @ max_val or @a out_val is NULL
+ *         then @max_val, @val_size is not 16/32 or @a out_val is NULL
  */
 size_t
 MHD_str_to_uvalue_n_ (const char *str,
diff --git a/src/microhttpd/mhd_threads.c b/src/microhttpd/mhd_threads.c
index 7291bfef..96182965 100644
--- a/src/microhttpd/mhd_threads.c
+++ b/src/microhttpd/mhd_threads.c
@@ -173,11 +173,13 @@ MHD_set_thread_name_ (const MHD_thread_ID_ thread_id,
 /**
  * Create a thread and set the attributes according to our options.
  *
+ * If thread is created, thread handle must be freed by MHD_join_thread_().
+ *
  * @param thread        handle to initialize
  * @param stack_size    size of stack for new thread, 0 for default
  * @param start_routine main function of thread
  * @param arg argument  for start_routine
- * @return non-zero on success; zero otherwise (with errno set)
+ * @return non-zero on success; zero otherwise
  */
 int
 MHD_create_thread_ (MHD_thread_handle_ID_ *thread,
diff --git a/src/microhttpd/sha1.h b/src/microhttpd/sha1.h
index 851a4429..9a3847e0 100644
--- a/src/microhttpd/sha1.h
+++ b/src/microhttpd/sha1.h
@@ -78,7 +78,7 @@ struct sha1_ctx
 /**
  * Initialise structure for SHA-1 calculation.
  *
- * @param ctx must be a `struct sha1_ctx *`
+ * @param ctx_ must be a `struct sha1_ctx *`
  */
 void
 MHD_SHA1_init (void *ctx_);