commit 76c60a727bdd0519831c9fe832709b64921d4535
parent 5d07bda6907d4a9ab9e70ddbeab256055db53b7d
Author: Evgeny Grin (Karlson2k) <k2k@drgrin.dev>
Date: Thu, 24 Apr 2025 18:38:05 +0200
More fixes for doxy and comments
Diffstat:
13 files changed, 29 insertions(+), 51 deletions(-)
diff --git a/src/mhd2/auth_digest.c b/src/mhd2/auth_digest.c
@@ -462,7 +462,7 @@ mhd_auth_digest_get_new_nonce (struct MHD_Connection *restrict c,
/**
* Get client's Digest Authorization algorithm type.
* If no algorithm is specified by client, MD5 is assumed.
- * @param params the Digest Authorization 'algorithm' parameter
+ * @param algo_param the Digest Authorization 'algorithm' parameter
* @return the algorithm type
*/
static enum MHD_DigestAuthAlgo
@@ -579,8 +579,7 @@ get_rq_dauth_qop (const struct mhd_RqDAuthParam *const qop_param)
/**
* Parse request Authorization header parameters for Digest Authentication
- * @param str the header string, everything after "Digest " substring
- * @param str_len the length of @a str in characters
+ * @param val the header string, everything after "Digest " substring
* @param[out] pdauth the pointer to the structure with Digest Authentication
* parameters
* @return true if parameters has been successfully parsed,
@@ -1719,7 +1718,6 @@ digest_update_buf (struct DigestAlgorithm *restrict da,
/**
* Feed digest calculation with single colon ':' character.
* @param da the digest calculation
- * @param str the zero-terminated string to process
*/
MHD_static_inline_ MHD_FN_PAR_NONNULL_ALL_ void
digest_update_with_colon (struct DigestAlgorithm *da)
@@ -2159,7 +2157,7 @@ enum mhd_CheckNonceNC
/**
* Check nonce-nc map array with the new nonce counter.
*
- * @param daemon the master daemon object
+ * @param d the master daemon object
* @param noncelen the length of @a nonce, in characters
* @param nonce the pointer that referenced hex nonce, does not need to be
* zero-terminated
@@ -3221,9 +3219,6 @@ digest_auth_check_all (struct MHD_Request *restrict req,
* @param username the username to be authenticated, must be in clear text
* even if userhash is used by the client
* @param password the password matching the @a username (and the @a realm)
- * @param nonce_timeout the period of seconds since nonce generation, when
- * the nonce is recognised as valid and not stale;
- * if zero is specified then daemon default value is used.
* @param max_nc the maximum allowed nc (Nonce Count) value, if client's nc
* exceeds the specified value then MHD_DAUTH_NONCE_STALE is
* returned;
diff --git a/src/mhd2/auth_digest.h b/src/mhd2/auth_digest.h
@@ -59,7 +59,7 @@ MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_ (2);
/**
* Find in request and parse Digest Authentication information
* @param req the request to use
- * @param[out] v_auth_basic_creds the pointer to set to the found data
+ * @param[out] v_auth_digest_info the pointer to set to the found data
* @return #MHD_SC_OK on success,
* error code otherwise
*/
diff --git a/src/mhd2/conn_mark_ready.h b/src/mhd2/conn_mark_ready.h
@@ -139,7 +139,6 @@ mhd_conn_mark_ready_update2 (struct MHD_Connection *restrict c,
* This function could be used if the "daemon" handle has not been extracted
* from the connection.
* @param c the connection to update
- * @param d the daemon for the connection
*/
MHD_static_inline_ MHD_FN_PAR_NONNULL_ALL_ void
mhd_conn_mark_ready_update (struct MHD_Connection *restrict c)
diff --git a/src/mhd2/daemon_start.c b/src/mhd2/daemon_start.c
@@ -1756,11 +1756,8 @@ daemon_init_large_buf (struct MHD_Daemon *restrict d,
/**
- * Initialise large buffer tracking.
+ * Deinitialise large buffer tracking.
* @param d the daemon object
- * @param s the user settings
- * @return #MHD_SC_OK on success,
- * the error code otherwise
*/
static MHD_FN_PAR_NONNULL_ (1) void
daemon_deinit_large_buf (struct MHD_Daemon *restrict d)
@@ -1931,8 +1928,6 @@ allocate_events (struct MHD_Daemon *restrict d)
/**
* Deallocate events data
* @param d the daemon object
- * @return #MHD_SC_OK on success,
- * the error code otherwise
*/
static MHD_FN_PAR_NONNULL_ (1) void
deallocate_events (struct MHD_Daemon *restrict d)
@@ -2033,8 +2028,6 @@ init_itc (struct MHD_Daemon *restrict d)
/**
* Deallocate events data
* @param d the daemon object
- * @return #MHD_SC_OK on success,
- * the error code otherwise
*/
static MHD_FN_PAR_NONNULL_ (1) void
deinit_itc (struct MHD_Daemon *restrict d)
@@ -2441,8 +2434,6 @@ init_individual_thread_data_events_conns (struct MHD_Daemon *restrict d,
* To be used only with non-master daemons.
* Do not start the thread even if configured for the internal threads.
* @param d the daemon object
- * @return #MHD_SC_OK on success,
- * the error code otherwise
*/
static MHD_FN_PAR_NONNULL_ (1) void
deinit_individual_thread_data_events_conns (struct MHD_Daemon *restrict d)
@@ -2634,7 +2625,6 @@ set_connections_total_limits (struct MHD_Daemon *restrict d,
* Set correct daemon threading type.
* Set the number of workers for thread pool type.
* @param d the daemon object
- * @param s the user settings
* @return #MHD_SC_OK on success,
* the error code otherwise
*/
@@ -2697,8 +2687,6 @@ set_d_threading_type (struct MHD_Daemon *restrict d)
* The threads must be not running.
* @param d the daemon object
* @param num_workers the number of workers to deinit
- * @return #MHD_SC_OK on success,
- * the error code otherwise
*/
static MHD_FN_PAR_NONNULL_ (1) void
deinit_workers_pool (struct MHD_Daemon *restrict d,
@@ -2733,7 +2721,7 @@ deinit_workers_pool (struct MHD_Daemon *restrict d,
/**
* Nullify worker daemon member that should be set only in master daemon
- * @param d
+ * @param d the daemon object
*/
static MHD_FN_PAR_NONNULL_ (1) void
reset_master_only_areas (struct MHD_Daemon *restrict d)
@@ -2938,9 +2926,6 @@ daemon_init_threading_and_conn (struct MHD_Daemon *restrict d,
* Also deallocate events and de-initialise daemon's connection data.
* No daemon-manged threads should be running.
* @param d the daemon object
- * @param s the user settings
- * @return #MHD_SC_OK on success,
- * the error code otherwise
*/
static MHD_FN_PAR_NONNULL_ (1) void
daemon_deinit_threading_and_conn (struct MHD_Daemon *restrict d)
@@ -3051,8 +3036,6 @@ start_individual_daemon_thread (struct MHD_Daemon *restrict d)
* pool mode.
* Must be called only for daemons with internal threads.
* @param d the daemon object, must be completely initialised
- * @return #MHD_SC_OK on success,
- * the error code otherwise
*/
MHD_FN_PAR_NONNULL_ (1) static void
stop_individual_daemon_thread (struct MHD_Daemon *restrict d)
diff --git a/src/mhd2/mhd_lib_init.h b/src/mhd2/mhd_lib_init.h
@@ -48,14 +48,17 @@ mhd_lib_deinit_global_if_needed (void);
/**
* Check whether the library has been successfully completely initialised.
- * @return
+ * @return 'true' if the library has been successfully initialised at least
+ * one time,
+ * 'false' otherwise
*/
MHD_INTERNAL bool
mhd_lib_is_fully_initialised_once (void);
/**
* Check whether the library is in fully initialised state now.
- * @return
+ * @return 'true' if the library is in fully initialised state now,
+ * 'false' otherwise
*/
MHD_INTERNAL bool
mhd_lib_is_fully_initialised_now (void);
diff --git a/src/mhd2/mhd_recv.h b/src/mhd2/mhd_recv.h
@@ -49,7 +49,7 @@ struct MHD_Connection; /* forward declaration */
MHD_INTERNAL enum mhd_SocketError
mhd_recv (struct MHD_Connection *restrict c,
size_t buf_size,
- char buffer[MHD_FN_PAR_DYN_ARR_SIZE_ (buf_size)],
+ char buf[MHD_FN_PAR_DYN_ARR_SIZE_ (buf_size)],
size_t *restrict received)
MHD_FN_PAR_NONNULL_ALL_ MHD_FN_PAR_OUT_SIZE_(3,2) MHD_FN_PAR_OUT_ (4);
diff --git a/src/mhd2/response_from.c b/src/mhd2/response_from.c
@@ -373,7 +373,9 @@ MHD_response_from_pipe (enum MHD_HTTP_StatusCode sc,
* @param spec_hdr_len the length of the @a spec_hdr
* @param spec_hdr the special header line, without last CRLF,
* if not NULL it will be deallocated by free().
- * @return
+ * @return the pointer to the created object if succeed,
+ * NULL otherwise
+ *
*/
MHD_INTERNAL
MHD_FN_PAR_CSTR_ (3) MHD_FN_PAR_CSTR_ (5) struct MHD_Response *
diff --git a/src/mhd2/response_funcs.h b/src/mhd2/response_funcs.h
@@ -55,7 +55,7 @@ MHD_FN_PAR_NONNULL_ALL_;
/**
* Check whether response is "frozen" (modifications blocked) and "freeze"
* it if not frozen before
- * @param response the response to manipulate
+ * @param r the response to manipulate
*/
MHD_INTERNAL void
mhd_response_check_frozen_freeze (struct MHD_Response *restrict r)
diff --git a/src/mhd2/stream_process_reply.c b/src/mhd2/stream_process_reply.c
@@ -243,7 +243,7 @@ is_reply_body_needed (struct MHD_Connection *restrict c,
* Reply properties include presence of reply body, transfer-encoding
* type and other.
*
- * @param connection to connection to process
+ * @param c the connection to process
*/
static MHD_FN_PAR_NONNULL_ALL_ void
setup_reply_properties (struct MHD_Connection *restrict c)
@@ -343,7 +343,7 @@ setup_reply_properties (struct MHD_Connection *restrict c)
/**
* Check whether queued response is suitable for @a connection.
- * @param connection to connection to check
+ * @param c the connection to check
*/
static void
check_connection_reply (struct MHD_Connection *restrict c)
@@ -525,7 +525,7 @@ buffer_append (char *buf,
* @param buf the buffer to add headers to
* @param ppos the pointer to the position in the @a buf
* @param buf_size the size of the @a buf
- * @param response the response
+ * @param r the response
* @param filter_content_len skip "Content-Length" header if any
* @param add_close add "close" token to the
* "Connection:" header (if any), ignored if no "Connection:"
diff --git a/src/mhd2/stream_process_request.c b/src/mhd2/stream_process_request.c
@@ -1557,7 +1557,7 @@ enum MHD_FIXED_ENUM_ mhd_HdrLineReadRes
* @param process_footers if true then footers are processed,
* if false then headers are processed
* @param[out] hdr_name the name of the parsed header (field)
- * @param[out] hdr_name the value of the parsed header (field)
+ * @param[out] hdr_value the value of the parsed header (field)
* @return mhd_HdrLineReadRes value
*/
static enum mhd_HdrLineReadRes
@@ -2551,11 +2551,6 @@ parse_cookie_header (struct MHD_Connection *restrict connection,
* Send error reply when receive buffer space exhausted while receiving or
* storing the request headers
* @param c the connection to handle
- * @param add_header the optional pointer to the current header string being
- * processed or the header failed to be added.
- * Could be not zero-terminated and can contain binary zeros.
- * Can be NULL.
- * @param add_header_size the size of the @a add_header
*/
MHD_static_inline_ void
handle_req_cookie_no_space (struct MHD_Connection *restrict c)
@@ -3594,11 +3589,12 @@ mhd_stream_process_req_recv_finished (struct MHD_Connection *restrict c)
* Send error reply when receive buffer space exhausted while receiving
* the chunk size line.
* @param c the connection to handle
- * @param add_header the optional pointer to the partially received
- * the current chunk size line.
- * Could be not zero-terminated and can contain binary zeros.
- * Can be NULL.
- * @param add_header_size the size of the @a add_header
+ * @param chunk_size_line the optional pointer to the partially received
+ * the current chunk size line.
+ * Could be not zero-terminated and can contain binary
+ * zeros.
+ * Can be NULL.
+ * @param chunk_size_line_size the size of the @a chunk_size_line
*/
static void
handle_req_chunk_size_line_no_space (struct MHD_Connection *c,
diff --git a/src/mhd2/stream_process_request.h b/src/mhd2/stream_process_request.h
@@ -65,7 +65,6 @@ typedef bool
* clobbered in the process!
* @param cb function to call on each key-value pair found
* @param cls the iterator context
- * @param[out] enc_broken the pointer to get
* @return false on failure
* true on success (parsing succeeded, @a cb always returned true)
*/
diff --git a/src/mhd2/tls_open_funcs.c b/src/mhd2/tls_open_funcs.c
@@ -514,7 +514,7 @@ daemon_deinit_ctx (struct mhd_TlsOpenDaemonData *restrict d_tls)
* Load the certificates chain from the OpenSSL BIO
* @param d the daemon handle
* @param d_tls the daemon TLS settings
- * @param s the application-provided settings
+ * @param bio the certificates chain data opened in OpenSSL BIO
* @return #MHD_SC_OK on success,
* error code otherwise
*/
diff --git a/src/mhd2/upgrade_prep.h b/src/mhd2/upgrade_prep.h
@@ -53,7 +53,8 @@ struct MHD_NameValueCStr; /* Forward declaration */
* can be NULL if @a num_headers is zero
* @param is_upload_act must be set to 'true' if the action being created is
* "upload" kind of action
- * @return
+ * @return 'true' if succeed,
+ * 'false' otherwise
*/
MHD_INTERNAL bool
mhd_upgrade_prep_for_action (struct MHD_Request *restrict req,
