commit 6d67eadb614da29ac4b143c68064bb7268e30060
parent 6f1b7c2c2265da31a4eaaeaf1cbb1a809020c125
Author: Evgeny Grin (Karlson2k) <k2k@narod.ru>
Date: Wed, 29 Dec 2021 10:47:14 +0300
Doxy corrections, fixes, and sync
Diffstat:
15 files changed, 64 insertions(+), 36 deletions(-)
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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_);
