From 9478de8082627d82412fa19f9480415f9bde2c71 Mon Sep 17 00:00:00 2001
From: Sudharshan Hegde <sudharshanhegde68@gmail.com>
Date: Tue, 10 Mar 2026 18:16:42 +0530
Subject: [PATCH] doc: add missing Doxygen comments and fix documentation style

- Add missing @brief, @param, and @return docs across src/ and include/
- Fix blank lines between doc comments and function definitions
- Move function docs from headers to corresponding .c files
- Use named constants (SSH_OK, SSH_ERROR, SSH_TIMEOUT_INFINITE) in docs
- Fix parameter ordering in error.c, buffer.c, log.c docs
- Place #ifdef-guarded docs inside their respective #ifdef blocks

Signed-off-by: Sudharshan Hegde <sudharshanhegde68@gmail.com>
Reviewed-by: Jakub Jelen <jjelen@redhat.com>
---
 doc/doc_coverage.sh          |   2 +-
 include/libssh/bind_config.h |   7 +-
 include/libssh/callbacks.h   |  34 +++++++-
 include/libssh/misc.h        |   6 ++
 include/libssh/server.h      |   5 ++
 include/libssh/sftp.h        |  70 +++++++++++++++-
 include/libssh/sftpserver.h  |  21 ++++-
 src/buffer.c                 |  16 ++++
 src/config.c                 |  23 +++---
 src/error.c                  |   5 +-
 src/legacy.c                 |  10 +++
 src/log.c                    |  51 +++++++++++-
 src/misc.c                   | 151 ++++++++++++++++++++++++++++++++---
 src/options.c                |  24 ++++++
 src/poll.c                   |  34 ++++++++
 src/session.c                |   4 +-
 src/sftpserver.c             |  27 +++++--
 src/socket.c                 |  31 +++++++
 src/threads.c                |   9 +++
 19 files changed, 484 insertions(+), 46 deletions(-)

diff --git a/doc/doc_coverage.sh b/doc/doc_coverage.sh
index 2f653275..6ea63cd3 100755
--- a/doc/doc_coverage.sh
+++ b/doc/doc_coverage.sh
@@ -49,4 +49,4 @@ ALL_FUNC=$(echo "$FUNC_LINES" | sed -e "s/$F_CUT_BEFORE//g" -e "s/$F_CUT_AFTER//
 ALL_FUNC=$(echo "$ALL_FUNC" | sort - | uniq | wc -l)
 
 # percentage of the documented functions
-awk "BEGIN {printf \"Documentation coverage is %.2f%\n\", 100 - (${UNDOC_FUNC}/${ALL_FUNC}*100)}"
+awk "BEGIN {printf \"Documentation coverage is %.2f%%\n\", 100 - (${UNDOC_FUNC}/${ALL_FUNC}*100)}"
diff --git a/include/libssh/bind_config.h b/include/libssh/bind_config.h
index 3271b5bf..28678fe8 100644
--- a/include/libssh/bind_config.h
+++ b/include/libssh/bind_config.h
@@ -57,10 +57,11 @@ enum ssh_bind_config_opcode_e {
     BIND_CFG_MAX /* Keep this one last in the list */
 };
 
-/* @brief Parse configuration file and set the options to the given ssh_bind
+/**
+ * @brief Parse configuration file and set the options to the given ssh_bind
  *
- * @params[in] sshbind   The ssh_bind context to be configured
- * @params[in] filename  The path to the configuration file
+ * @param[in] sshbind   The ssh_bind context to be configured
+ * @param[in] filename  The path to the configuration file
  *
  * @returns    0 on successful parsing the configuration file, -1 on error
  */
diff --git a/include/libssh/callbacks.h b/include/libssh/callbacks.h
index 639808c5..e7bb1b30 100644
--- a/include/libssh/callbacks.h
+++ b/include/libssh/callbacks.h
@@ -538,12 +538,9 @@ typedef struct ssh_socket_callbacks_struct *ssh_socket_callbacks;
  * automatically passed through.
  *
  * @param list     list of callbacks
- *
  * @param cbtype   type of the callback
- *
  * @param c        callback name
- *
- * @param va_args parameters to be passed
+ * @param ...      Parameters to be passed to the callback.
  */
 #define ssh_callbacks_execute_list(list, cbtype, c, ...)      \
     do {                                                      \
@@ -585,9 +582,18 @@ typedef struct ssh_socket_callbacks_struct *ssh_socket_callbacks;
             _cb = ssh_iterator_value(_cb_type, _cb_i);                \
             if (ssh_callbacks_exists(_cb, _cb_name))
 
+/** @internal
+ * @brief Execute the current callback in an ssh_callbacks_iterate() loop.
+ *
+ * @param _cb_name  The name of the callback field to invoke.
+ * @param ...       Parameters to be passed to the callback.
+ */
 #define ssh_callbacks_iterate_exec(_cb_name, ...) \
                 _cb->_cb_name(__VA_ARGS__, _cb->userdata)
 
+/** @internal
+ * @brief End an ssh_callbacks_iterate() loop.
+ */
 #define ssh_callbacks_iterate_end() \
         }                           \
     } while(0)
@@ -1060,8 +1066,18 @@ LIBSSH_API int ssh_remove_channel_callbacks(ssh_channel channel,
  * @{
  */
 
+/** @brief Callback for thread mutex operations (init, destroy, lock, unlock).
+ *
+ * @param lock  Pointer to the mutex lock.
+ *
+ * @return      0 on success, non-zero on error.
+ */
 typedef int (*ssh_thread_callback) (void **lock);
 
+/** @brief Callback to retrieve the current thread identifier.
+ *
+ * @return  The unique identifier of the calling thread.
+ */
 typedef unsigned long (*ssh_thread_id_callback) (void);
 struct ssh_threads_callbacks_struct {
 	const char *type;
@@ -1172,10 +1188,20 @@ typedef int (*ssh_jump_verify_knownhost_callback)(ssh_session session,
 typedef int (*ssh_jump_authenticate_callback)(ssh_session session,
                                               void *userdata);
 
+/**
+ * @brief Callback collection for managing an SSH proxyjump connection.
+ *
+ * Set these callbacks to control knownhost verification and authentication
+ * on the jump host before the final destination is reached.
+ */
 struct ssh_jump_callbacks_struct {
+    /** Userdata passed to each callback. */
     void *userdata;
+    /** Called before connecting to the jump host. */
     ssh_jump_before_connection_callback before_connection;
+    /** Called to verify the jump host's identity. */
     ssh_jump_verify_knownhost_callback verify_knownhost;
+    /** Called to authenticate on the jump host. */
     ssh_jump_authenticate_callback authenticate;
 };
 
diff --git a/include/libssh/misc.h b/include/libssh/misc.h
index 132d197e..b7716a5f 100644
--- a/include/libssh/misc.h
+++ b/include/libssh/misc.h
@@ -70,9 +70,15 @@ struct ssh_iterator {
   const void *data;
 };
 
+/**
+ * @brief Holds connection details for an SSH proxyjump host.
+ */
 struct ssh_jump_info_struct {
+    /** Hostname or IP address of the jump host. */
     char *hostname;
+    /** Username to authenticate with on the jump host. */
     char *username;
+    /** Port number of the jump host. */
     int port;
 };
 
diff --git a/include/libssh/server.h b/include/libssh/server.h
index 7b72ebd8..a0fc280e 100644
--- a/include/libssh/server.h
+++ b/include/libssh/server.h
@@ -35,6 +35,11 @@
 extern "C" {
 #endif
 
+/**
+ * @brief Options for configuring an SSH server bind session.
+ *
+ * Used with ssh_bind_options_set() to configure server-side options.
+ */
 enum ssh_bind_options_e {
     SSH_BIND_OPTIONS_BINDADDR,
     SSH_BIND_OPTIONS_BINDPORT,
diff --git a/include/libssh/sftp.h b/include/libssh/sftp.h
index 7676d89b..f0e783d2 100644
--- a/include/libssh/sftp.h
+++ b/include/libssh/sftp.h
@@ -64,6 +64,7 @@ extern "C" {
 #endif /* _MSC_VER */
 #endif /* _WIN32 */
 
+/** @brief The SFTP protocol version implemented by this library. */
 #define LIBSFTP_VERSION 3
 
 typedef struct sftp_attributes_struct* sftp_attributes;
@@ -90,10 +91,76 @@ typedef struct sftp_request_queue_struct* sftp_request_queue;
  * @see sftp_free
  */
 typedef struct sftp_session_struct* sftp_session;
+
+/**
+ * @brief Handle for an SFTP status message received from the server.
+ *
+ * This type represents a status response returned by the SFTP server in
+ * reply to a client request. It carries a numeric status code and an optional
+ * human-readable error message. This type is used internally by libssh and
+ * is not part of the public API.
+ *
+ * @see sftp_status_message_struct
+ */
 typedef struct sftp_status_message_struct* sftp_status_message;
+
+/**
+ * @brief Handle for SFTP file system statistics.
+ *
+ * This type represents file system statistics as reported by the SFTP server,
+ * analogous to the POSIX @c statvfs structure. It is obtained via
+ * sftp_statvfs() or sftp_fstatvfs() and must be freed with
+ * sftp_statvfs_free().
+ *
+ * @see sftp_statvfs_struct
+ * @see sftp_statvfs
+ * @see sftp_fstatvfs
+ * @see sftp_statvfs_free
+ */
 typedef struct sftp_statvfs_struct* sftp_statvfs_t;
+
+/**
+ * @brief Handle for SFTP server limits information.
+ *
+ * This type represents the server-reported SFTP limits such as the maximum
+ * packet, read, and write lengths and the maximum number of open handles.
+ * It is obtained via sftp_limits() and must be freed with sftp_limits_free().
+ *
+ * @see sftp_limits_struct
+ * @see sftp_limits
+ * @see sftp_limits_free
+ */
 typedef struct sftp_limits_struct* sftp_limits_t;
+
+/**
+ * @brief Handle for an asynchronous SFTP I/O operation.
+ *
+ * This type represents an in-flight asynchronous SFTP read or write request.
+ * It is allocated by sftp_aio_begin_read() or sftp_aio_begin_write() and
+ * consumed by the corresponding sftp_aio_wait_read() or sftp_aio_wait_write()
+ * call. If the wait call is not reached, the handle must be freed explicitly
+ * with sftp_aio_free() to avoid memory leaks.
+ *
+ * @see sftp_aio_begin_read
+ * @see sftp_aio_wait_read
+ * @see sftp_aio_begin_write
+ * @see sftp_aio_wait_write
+ * @see sftp_aio_free
+ */
 typedef struct sftp_aio_struct* sftp_aio;
+
+/**
+ * @brief Handle for an SFTP name-to-id mapping.
+ *
+ * This type stores a mapping between numeric user or group IDs and their
+ * corresponding names. It is allocated via sftp_name_id_map_new(), populated
+ * by sftp_get_users_groups_by_id(), and freed with sftp_name_id_map_free().
+ *
+ * @see sftp_name_id_map_struct
+ * @see sftp_name_id_map_new
+ * @see sftp_get_users_groups_by_id
+ * @see sftp_name_id_map_free
+ */
 typedef struct sftp_name_id_map_struct *sftp_name_id_map;
 
 struct sftp_session_struct {
@@ -392,7 +459,6 @@ LIBSSH_API sftp_session sftp_new(ssh_session session);
  */
 LIBSSH_API sftp_session sftp_new_channel(ssh_session session, ssh_channel channel);
 
-
 /**
  * @brief Close and deallocate a sftp session.
  *
@@ -1582,7 +1648,9 @@ LIBSSH_API void sftp_handle_remove(sftp_session sftp, void *handle);
 #define SFTP_EXTENDED SSH_FXP_EXTENDED
 
 /* openssh flags */
+/** @brief statvfs flag: file system is mounted read-only. */
 #define SSH_FXE_STATVFS_ST_RDONLY 0x1 /* read-only */
+/** @brief statvfs flag: file system does not support setuid/setgid. */
 #define SSH_FXE_STATVFS_ST_NOSUID 0x2 /* no setuid */
 
 #ifdef __cplusplus
diff --git a/include/libssh/sftpserver.h b/include/libssh/sftpserver.h
index 01b17c7f..0832130e 100644
--- a/include/libssh/sftpserver.h
+++ b/include/libssh/sftpserver.h
@@ -43,17 +43,35 @@ extern "C" {
  * @{
  */
 
+/**
+ * @brief Macro to declare an SFTP message callback function.
+ *
+ * @param name  The name of the callback function to declare.
+ */
 #define SSH_SFTP_CALLBACK(name) \
     static int name(sftp_client_message message)
 
+/**
+ * @brief Callback for handling SFTP client messages.
+ *
+ * @param message  The SFTP client message to handle.
+ *
+ * @return  0 on success, -1 on error.
+ */
 typedef int (*sftp_server_message_callback)(sftp_client_message message);
 
+/**
+ * @brief Maps an SFTP message type to its handler callback.
+ */
 struct sftp_message_handler
 {
+    /** The name of the SFTP operation (e.g. "read", "write"). */
     const char *name;
+    /** The extended operation name for SSH_FXP_EXTENDED requests, or NULL. */
     const char *extended_name;
+    /** The SFTP message type code (e.g. SSH_FXP_READ). */
     uint8_t type;
-
+    /** The callback function to invoke for this message type. */
     sftp_server_message_callback cb;
 };
 
@@ -61,6 +79,7 @@ LIBSSH_API int sftp_channel_default_subsystem_request(ssh_session session,
                                                       ssh_channel channel,
                                                       const char *subsystem,
                                                       void *userdata);
+
 LIBSSH_API int sftp_channel_default_data_callback(ssh_session session,
                                                   ssh_channel channel,
                                                   void *data,
diff --git a/src/buffer.c b/src/buffer.c
index 3499ce27..db713079 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -109,6 +109,11 @@ static void buffer_verify(ssh_buffer buf)
 }
 
 #else
+/** @internal
+ * @brief No-op stub for buffer_verify when debug checks are disabled.
+ *
+ * @param x  The buffer to verify (ignored).
+ */
 #define buffer_verify(x)
 #endif
 
@@ -964,9 +969,12 @@ static int ssh_buffer_pack_allocate_va(struct ssh_buffer_struct *buffer,
 
 /** @internal
  * @brief Add multiple values in a buffer on a single function call
+ * 
  * @param[in] buffer    The buffer to add to
  * @param[in] format    A format string of arguments.
+ * @param[in] argc      Number of arguments passed after format.
  * @param[in] ap        A va_list of arguments.
+ * 
  * @returns             SSH_OK on success
  *                      SSH_ERROR on error
  * @see ssh_buffer_add_format() for format list values.
@@ -1112,6 +1120,9 @@ ssh_buffer_pack_va(struct ssh_buffer_struct *buffer,
  *                         'P': size_t, void * (len of data, pointer to data)
  *                              only pushes data.
  *                         'B': bignum (pushed as SSH string)
+ * @param[in] argc      Number of arguments passed after format.
+ * @param[in] ...       Arguments as described by the format string.
+ * 
  * @returns             SSH_OK on success
  *                      SSH_ERROR on error
  * @warning             when using 'P' with a constant size (e.g. 8), do not
@@ -1148,7 +1159,9 @@ int _ssh_buffer_pack(struct ssh_buffer_struct *buffer,
  * @brief Get multiple values from a buffer on a single function call
  * @param[in] buffer    The buffer to get from
  * @param[in] format    A format string of arguments.
+ * @param[in] argc      Number of arguments passed in the va_list.
  * @param[in] ap        A va_list of arguments.
+ * 
  * @returns             SSH_OK on success
  *                      SSH_ERROR on error
  * @see ssh_buffer_get_format() for format list values.
@@ -1411,6 +1424,9 @@ cleanup:
  *                         'P': size_t, void ** (len of data, pointer to data)
  *                              only pulls data.
  *                         'B': bignum * (pulled as SSH string)
+ * @param[in] argc      Number of arguments passed after format.
+ * @param[in] ...       Arguments as described by the format string.
+ * 
  * @returns             SSH_OK on success
  *                      SSH_ERROR on error
  * @warning             when using 'P' with a constant size (e.g. 8), do not
diff --git a/src/config.c b/src/config.c
index e2b3545f..5172cfbe 100644
--- a/src/config.c
+++ b/src/config.c
@@ -1684,11 +1684,12 @@ int ssh_config_parse_line_cli(ssh_session session, const char *line)
                                           true);
 }
 
-/* @brief Parse configuration from a file pointer
+/** 
+ * @brief Parse configuration from a file pointer
  *
- * @params[in] session   The ssh session
- * @params[in] fp        A valid file pointer
- * @params[in] global    Whether the config is global or not
+ * @param[in] session   The ssh session
+ * @param[in] fp        A valid file pointer
+ * @param[in] global    Whether the config is global or not
  *
  * @returns    0 on successful parsing the configuration file, -1 on error
  */
@@ -1710,10 +1711,11 @@ int ssh_config_parse(ssh_session session, FILE *fp, bool global)
     return 0;
 }
 
-/* @brief Parse configuration file and set the options to the given session
+/** 
+ * @brief Parse configuration file and set the options to the given session
  *
- * @params[in] session   The ssh session
- * @params[in] filename  The path to the ssh configuration file
+ * @param[in] session   The ssh session
+ * @param[in] filename  The path to the ssh configuration file
  *
  * @returns    0 on successful parsing the configuration file, -1 on error
  */
@@ -1748,10 +1750,11 @@ int ssh_config_parse_file(ssh_session session, const char *filename)
     return rv;
 }
 
-/* @brief Parse configuration string and set the options to the given session
+/** 
+ * @brief Parse configuration string and set the options to the given session
  *
- * @params[in] session   The ssh session
- * @params[in] input     Null terminated string containing the configuration
+ * @param[in] session   The ssh session
+ * @param[in] input     Null terminated string containing the configuration
  *
  * @returns    SSH_OK on successful parsing the configuration string,
  *             SSH_ERROR on error
diff --git a/src/error.c b/src/error.c
index 3f8d78cd..d28fbd9c 100644
--- a/src/error.c
+++ b/src/error.c
@@ -43,11 +43,9 @@
  * @brief Registers an error with a description.
  *
  * @param  error       The place to store the error.
- *
  * @param  code        The class of error.
- *
+ * @param  function    The name of the calling function.
  * @param  descr       The description, which can be a format string.
- *
  * @param  ...         The arguments for the format string.
  */
 void _ssh_set_error(void *error,
@@ -76,6 +74,7 @@ void _ssh_set_error(void *error,
  * @brief Registers an out of memory error
  *
  * @param  error       The place to store the error.
+ * @param  function    The name of the calling function.
  *
  */
 void _ssh_set_error_oom(void *error, const char *function)
diff --git a/src/legacy.c b/src/legacy.c
index 5fad635f..e017acec 100644
--- a/src/legacy.c
+++ b/src/legacy.c
@@ -770,6 +770,16 @@ ssh_string ssh_get_pubkey(ssh_session session)
  ****************************************************************************/
 
 #ifdef WITH_SERVER
+
+/**
+ * @brief Accept an incoming SSH connection on a bind socket.
+ *
+ * @deprecated  Use ssh_bind_accept() instead.
+ *
+ * @param session  The SSH session to accept the connection on.
+ *
+ * @return  SSH_OK on success, SSH_ERROR on error.
+ */
 int ssh_accept(ssh_session session) {
     return ssh_handle_key_exchange(session);
 }
diff --git a/src/log.c b/src/log.c
index 8bc8ccab..c7d9b61c 100644
--- a/src/log.c
+++ b/src/log.c
@@ -109,6 +109,16 @@ static void ssh_log_custom(ssh_logging_callback log_fn,
     log_fn(verbosity, function, buf, ssh_get_log_userdata());
 }
 
+/** @internal
+ * @brief Dispatch a pre-formatted log message to the active logging backend.
+ *
+ * If a custom logging callback is registered, the message is passed to it.
+ * Otherwise, the message is written to stderr.
+ *
+ * @param verbosity  The verbosity level of the message.
+ * @param function   The name of the calling function.
+ * @param buffer     The already-formatted log message string.
+ */
 void ssh_log_function(int verbosity,
                       const char *function,
                       const char *buffer)
@@ -123,6 +133,15 @@ void ssh_log_function(int verbosity,
     ssh_log_stderr(verbosity, function, buffer);
 }
 
+/** @internal
+ * @brief Format a log message from a va_list and dispatch it for logging.
+ *
+ * @param verbosity  The verbosity level of the message.
+ * @param function   The name of the calling function.
+ * @param format     A printf-style format string.
+ * @param va         Pointer to the variable argument list
+ *                   for the format string.
+ */
 void ssh_vlog(int verbosity,
               const char *function,
               const char *format,
@@ -134,6 +153,15 @@ void ssh_vlog(int verbosity,
     ssh_log_function(verbosity, function, buffer);
 }
 
+/** @internal
+ * @brief Log a message if the given verbosity does not 
+ *                   exceed the global log level.
+ *
+ * @param verbosity  The verbosity level of the message.
+ * @param function   The name of the calling function.
+ * @param format     A printf-style format string.
+ * @param ...        Additional arguments corresponding to the format string.
+ */
 void _ssh_log(int verbosity,
               const char *function,
               const char *format, ...)
@@ -149,6 +177,15 @@ void _ssh_log(int verbosity,
 
 /* LEGACY */
 
+/** @brief Log a message using the verbosity level of the given session.
+ *
+ * @deprecated      Use the SSH_LOG() macro instead.
+ *
+ * @param session    The SSH session whose verbosity level is checked.
+ * @param verbosity  The verbosity level of the message.
+ * @param format     A printf-style format string.
+ * @param  ...       Arguments as described by the format string.
+ */
 void ssh_log(ssh_session session,
              int verbosity,
              const char *format, ...)
@@ -164,9 +201,14 @@ void ssh_log(ssh_session session,
 
 /** @internal
  * @brief log a SSH event with a common pointer
- * @param common       The SSH/bind session.
- * @param verbosity     The verbosity of the event.
- * @param format        The format string of the log entry.
+ *
+ * Works for both ssh_session and ssh_bind as both embed ssh_common_struct.
+ *
+ * @param common     The SSH/bind session.
+ * @param verbosity  The verbosity of the event.
+ * @param function   The name of the calling function.
+ * @param format     The format string of the log entry.
+ * @param ...        Additional arguments corresponding to the format string.
  */
 void ssh_log_common(struct ssh_common_struct *common,
                     int verbosity,
@@ -221,6 +263,9 @@ int ssh_set_log_callback(ssh_logging_callback cb) {
   return SSH_OK;
 }
 
+/** @internal
+ * @brief Clear the thread-local logging callback, reverting to stderr logging.
+ */
 void
 _ssh_reset_log_cb(void)
 {
diff --git a/src/misc.c b/src/misc.c
index 6043e573..46204b11 100644
--- a/src/misc.c
+++ b/src/misc.c
@@ -127,7 +127,13 @@ static char *ssh_get_user_home_dir_internal(void)
     return NULL;
 }
 
-/* we have read access on file */
+/** @internal
+ * @brief Check whether the current process has read access to a file.
+ *
+ * @param[in] file  Path to the file to check.
+ *
+ * @return  1 if the file is readable, 0 otherwise.
+ */
 int ssh_file_readaccess_ok(const char *file)
 {
     if (_access(file, 4) < 0) {
@@ -208,11 +214,11 @@ struct tm *ssh_localtime(const time_t *timer, struct tm *result)
     return result;
 }
 
-/**
- * @brief  Get username from the calling process.
+/** @internal
+ * @brief Get the username of the currently running process.
  *
- * @return An allocated string with the user on success, NULL on failure. The
- * caller is responsible for freeing returned string.
+ * @return  A newly allocated string with the username, or NULL on error.
+ *          The caller is responsible for freeing it.
  */
 char *ssh_get_local_username(void)
 {
@@ -240,6 +246,13 @@ char *ssh_get_local_username(void)
     return NULL;
 }
 
+/** @internal
+ * @brief Check whether a string is a valid IPv4 address.
+ *
+ * @param[in] str  The string to check.
+ *
+ * @return  1 if the string is a valid IPv4 address, 0 otherwise.
+ */
 int ssh_is_ipaddr_v4(const char *str)
 {
     struct sockaddr_storage ss;
@@ -263,6 +276,13 @@ int ssh_is_ipaddr_v4(const char *str)
     return 0;
 }
 
+/** @internal
+ * @brief Check whether a string is a valid IPv4 or IPv6 address.
+ *
+ * @param[in] str  The string to check.
+ *
+ * @return  1 if valid IP address, 0 if not, -1 on memory error.
+ */
 int ssh_is_ipaddr(const char *str)
 {
     int rc = SOCKET_ERROR;
@@ -328,7 +348,13 @@ static char *ssh_get_user_home_dir_internal(void)
     return szPath;
 }
 
-/* we have read access on file */
+/** @internal
+ * @brief Check whether the current process has read access to a file.
+ *
+ * @param[in] file  Path to the file to check.
+ *
+ * @return  1 if the file is readable, 0 otherwise.
+ */
 int ssh_file_readaccess_ok(const char *file)
 {
     if (access(file, R_OK) < 0) {
@@ -363,11 +389,11 @@ int ssh_dir_writeable(const char *path)
     return 0;
 }
 
-/**
- * @brief  Get username from the calling process.
+/** @internal
+ * @brief Get the username of the currently running process.
  *
- * @return An allocated string with the name on success, NULL on failure. The
- * caller is responsible for freeing returned string.
+ * @return  A newly allocated string with the username, or NULL on error.
+ *          The caller is responsible for freeing it.
  */
 char *ssh_get_local_username(void)
 {
@@ -393,6 +419,13 @@ char *ssh_get_local_username(void)
     return name;
 }
 
+/** @internal
+ * @brief Check whether a string is a valid IPv4 address.
+ *
+ * @param[in] str  The string to check.
+ *
+ * @return  1 if the string is a valid IPv4 address, 0 otherwise.
+ */
 int ssh_is_ipaddr_v4(const char *str)
 {
     int rc = -1;
@@ -406,6 +439,13 @@ int ssh_is_ipaddr_v4(const char *str)
     return 0;
 }
 
+/** @internal
+ * @brief Check whether a string is a valid IPv4 or IPv6 address.
+ *
+ * @param[in] str  The string to check.
+ *
+ * @return  1 if valid IP address, 0 if not, -1 on memory error.
+ */
 int ssh_is_ipaddr(const char *str)
 {
     int rc = -1;
@@ -440,6 +480,17 @@ int ssh_is_ipaddr(const char *str)
 
 #endif /* _WIN32 */
 
+/** @internal
+ * @brief Get the home directory of the current user.
+ *
+ * If a session is provided and a cached value exists, it is returned directly.
+ * Otherwise the home directory is looked up and cached in the session.
+ *
+ * @param[in] session  The SSH session to cache the result in, or NULL.
+ *
+ * @return  A newly allocated string with the home directory path, or NULL
+ *          on error. The caller is responsible for freeing it.
+ */
 char *ssh_get_user_home_dir(ssh_session session)
 {
     char *szPath = NULL;
@@ -463,6 +514,14 @@ char *ssh_get_user_home_dir(ssh_session session)
     return szPath;
 }
 
+/** @internal
+ * @brief Convert a string to lowercase.
+ *
+ * @param[in] str  The string to convert.
+ *
+ * @return  A newly allocated lowercase copy of the string, or NULL on error.
+ *          The caller is responsible for freeing it.
+ */
 char *ssh_lowercase(const char* str)
 {
     char *new = NULL, *p = NULL;
@@ -483,6 +542,15 @@ char *ssh_lowercase(const char* str)
     return new;
 }
 
+/** @internal
+ * @brief Format a host and port into a "[host]:port" string.
+ *
+ * @param[in] host  The hostname or IP address.
+ * @param[in] port  The port number.
+ *
+ * @return  A newly allocated string of the form "[host]:port", or NULL
+ *          on error. The caller is responsible for freeing it.
+ */
 char *ssh_hostport(const char *host, int port)
 {
     char *dest = NULL;
@@ -788,6 +856,11 @@ const char *ssh_version(int req_version)
     return NULL;
 }
 
+/** @internal
+ * @brief Create a new empty linked list.
+ *
+ * @return  A newly allocated ssh_list, or NULL on memory error.
+ */
 struct ssh_list *ssh_list_new(void)
 {
     struct ssh_list *ret = malloc(sizeof(struct ssh_list));
@@ -798,6 +871,13 @@ struct ssh_list *ssh_list_new(void)
     return ret;
 }
 
+/** @internal
+ * @brief Free a linked list and all its iterator nodes.
+ *
+ * The data pointed to by each node is not freed.
+ *
+ * @param[in] list  The list to free.
+ */
 void ssh_list_free(struct ssh_list *list)
 {
     struct ssh_iterator *ptr = NULL, *next = NULL;
@@ -812,6 +892,13 @@ void ssh_list_free(struct ssh_list *list)
     SAFE_FREE(list);
 }
 
+/** @internal
+ * @brief Get the first iterator of a linked list.
+ *
+ * @param[in] list  The list to iterate.
+ *
+ * @return  Pointer to the first iterator, or NULL if the list is empty.
+ */
 struct ssh_iterator *ssh_list_get_iterator(const struct ssh_list *list)
 {
     if (!list)
@@ -819,6 +906,14 @@ struct ssh_iterator *ssh_list_get_iterator(const struct ssh_list *list)
     return list->root;
 }
 
+/** @internal
+ * @brief Find the iterator pointing to a specific value in the list.
+ *
+ * @param[in] list   The list to search.
+ * @param[in] value  The data pointer to find.
+ *
+ * @return  The iterator pointing to the value, or NULL if not found.
+ */
 struct ssh_iterator *ssh_list_find(const struct ssh_list *list, void *value)
 {
     struct ssh_iterator *it = NULL;
@@ -894,6 +989,14 @@ int ssh_list_append(struct ssh_list *list, const void *data)
   return SSH_OK;
 }
 
+/** @internal
+ * @brief Prepend an element at the beginning of the list.
+ *
+ * @param[in] list  The list to prepend to.
+ * @param[in] data  The element to prepend.
+ *
+ * @return  `SSH_OK` on success, `SSH_ERROR` on error.
+ */
 int ssh_list_prepend(struct ssh_list *list, const void *data)
 {
   struct ssh_iterator *it = NULL;
@@ -919,6 +1022,12 @@ int ssh_list_prepend(struct ssh_list *list, const void *data)
   return SSH_OK;
 }
 
+/** @internal
+ * @brief Remove an element from the list by its iterator.
+ *
+ * @param[in] list      The list to remove from.
+ * @param[in] iterator  The iterator pointing to the element to remove.
+ */
 void ssh_list_remove(struct ssh_list *list, struct ssh_iterator *iterator)
 {
     struct ssh_iterator *ptr = NULL, *prev = NULL;
@@ -1257,6 +1366,12 @@ char *ssh_path_expand_tilde(const char *d)
     return r;
 }
 
+/** @internal
+ * @brief Get the hostname of the local machine.
+ *
+ * @return  A newly allocated string with the hostname, or NULL on error.
+ *          The caller is responsible for freeing it.
+ */
 char *ssh_get_local_hostname(void)
 {
     char host[NI_MAXHOST] = {0};
@@ -1359,6 +1474,7 @@ err:
 /** @internal
  * @brief expands a string in function of session options
  *
+ * @param[in] session  The SSH session providing option values for expansion.
  * @param[in] s Format string to expand. Known parameters:
  *               - %d user home directory (~)
  *               - %h target host name
@@ -1791,6 +1907,15 @@ void burn_free(void *ptr, size_t len)
 }
 
 #if !defined(HAVE_STRNDUP)
+
+/** @internal
+ * @brief Compatibility implementation of strndup for systems that lack it.
+ *
+ * @param[in] s  The string to duplicate.
+ * @param[in] n  Maximum number of characters to copy.
+ *
+ * @return  A newly allocated null-terminated string, or NULL on error.
+ */
 char *strndup(const char *s, size_t n)
 {
     char *x = NULL;
@@ -1811,7 +1936,11 @@ char *strndup(const char *s, size_t n)
 }
 #endif /* ! HAVE_STRNDUP */
 
-/* Increment 64b integer in network byte order */
+/** @internal
+ * @brief Increment a 64-bit counter stored in network byte order.
+ *
+ * @param[in,out] counter  Pointer to an 8-byte buffer holding the counter.
+ */
 void
 uint64_inc(unsigned char *counter)
 {
diff --git a/src/options.c b/src/options.c
index 63859b00..31b0e26e 100644
--- a/src/options.c
+++ b/src/options.c
@@ -288,6 +288,20 @@ int ssh_options_copy(ssh_session src, ssh_session *dest)
     return 0;
 }
 
+/** @internal
+ * @brief Set a key exchange algorithm list option on the session.
+ *
+ * Supports prefix modifiers: '+' to append, '-' to remove, '^' to prepend
+ * to the default algorithm list.
+ *
+ * @param[in]  session  The SSH session.
+ * @param[in]  algo     The algorithm type to configure.
+ * @param[in]  list     The algorithm list string.
+ * @param[out] place    Pointer to the string to store
+ *                      the resulting algorithm list.
+ *
+ * @return  `SSH_OK` on success, `SSH_ERROR` on error.
+ */
 int ssh_options_set_algo(ssh_session session,
                          enum ssh_kex_types_e algo,
                          const char *list,
@@ -2081,6 +2095,16 @@ out:
     return r;
 }
 
+/** @internal
+ * @brief Apply default values for unset session options.
+ *
+ * Sets default SSH directory and username if not already configured,
+ * and resolves any remaining option expansions.
+ *
+ * @param[in] session  The SSH session to apply defaults to.
+ *
+ * @return  `SSH_OK` on success, `SSH_ERROR` on error.
+ */
 int ssh_options_apply(ssh_session session)
 {
     char *tmp = NULL;
diff --git a/src/poll.c b/src/poll.c
index 23d18256..d3c2b40a 100644
--- a/src/poll.c
+++ b/src/poll.c
@@ -84,16 +84,33 @@ struct ssh_poll_ctx_struct {
 #ifdef HAVE_POLL
 #include <poll.h>
 
+/** @internal
+ * @brief Initialize the poll subsystem. No-op when native poll is available.
+ */
 void ssh_poll_init(void)
 {
     return;
 }
 
+/** @internal
+ * @brief Clean up the poll subsystem. No-op when native poll is available.
+ */
 void ssh_poll_cleanup(void)
 {
     return;
 }
 
+/** @internal
+ * @brief Wait for events on a set of file descriptors.
+ *
+ * @param fds      Array of pollfd structures specifying the file descriptors.
+ * @param nfds     Number of file descriptors in the array.
+ * @param timeout  Timeout in milliseconds, `SSH_TIMEOUT_INFINITE`
+ *                 to block indefinitely.
+ *
+ * @return         Number of file descriptors with events, 0 on timeout,
+ *                 -1 on error.
+ */
 int ssh_poll(ssh_pollfd_t *fds, nfds_t nfds, int timeout)
 {
     return poll((struct pollfd *)fds, nfds, timeout);
@@ -321,16 +338,33 @@ static int bsd_poll(ssh_pollfd_t *fds, nfds_t nfds, int timeout)
     return rc;
 }
 
+/** @internal
+ * @brief Initialize the poll subsystem using the BSD poll emulation.
+ */
 void ssh_poll_init(void)
 {
     ssh_poll_emu = bsd_poll;
 }
 
+/** @internal
+ * @brief Clean up the poll subsystem, resetting to the BSD poll emulation.
+ */
 void ssh_poll_cleanup(void)
 {
     ssh_poll_emu = bsd_poll;
 }
 
+/** @internal
+ * @brief Wait for events on a set of file descriptors.
+ *
+ * @param fds      Array of pollfd structures specifying the file descriptors.
+ * @param nfds     Number of file descriptors in the array.
+ * @param timeout  Timeout in milliseconds, `SSH_TIMEOUT_INFINITE`
+ *                 to block indefinitely.
+ *
+ * @return         Number of file descriptors with events, 0 on timeout,
+ *                 -1 on error.
+ */
 int ssh_poll(ssh_pollfd_t *fds, nfds_t nfds, int timeout)
 {
     return (ssh_poll_emu)(fds, nfds, timeout);
diff --git a/src/session.c b/src/session.c
index 13c7f79e..b9335ea2 100644
--- a/src/session.c
+++ b/src/session.c
@@ -1010,7 +1010,9 @@ int ssh_get_version(ssh_session session) {
 /**
  * @internal
  * @brief Callback to be called when the socket received an exception code.
- * @param user is a pointer to session
+ * @param code        The exception code from the socket layer.
+ * @param errno_code  The errno value associated with the exception.
+ * @param user        Pointer to the SSH session.
  */
 void ssh_socket_exception_callback(int code, int errno_code, void *user){
     ssh_session session = (ssh_session)user;
diff --git a/src/sftpserver.c b/src/sftpserver.c
index 4671845b..4210ccef 100644
--- a/src/sftpserver.c
+++ b/src/sftpserver.c
@@ -948,6 +948,14 @@ void *sftp_handle(sftp_session sftp, ssh_string handle)
     return sftp->handles[val];
 }
 
+/**
+ * @brief Remove an SFTP file or directory handle from the session.
+ *
+ * @param sftp    The SFTP session.
+ * @param handle  The handle to remove.
+ *
+ * @see sftp_handle_alloc()
+ */
 void sftp_handle_remove(sftp_session sftp, void *handle)
 {
     int i;
@@ -2071,16 +2079,19 @@ sftp_channel_default_subsystem_request(ssh_session session,
 }
 
 /**
- * @brief Default data callback for sftp server
+ * @brief Default channel data callback for an SFTP server subsystem.
  *
- * @param[in] session   The ssh session
- * @param[in] channel   The ssh channel with SFTP session opened
- * @param[in] data      The data to be processed.
- * @param[in] len       The length of input data to be processed
- * @param[in] is_stderr Unused channel flag for stderr flagging
- * @param[in] userdata  The pointer to sftp_session
+ * Processes incoming data on the channel and dispatches it to the SFTP
+ * server message handler.
  *
- * @return number of bytes processed, -1 when error occurs.
+ * @param[in] session   The SSH session.
+ * @param[in] channel   The SSH channel carrying the SFTP data.
+ * @param[in] data      The received data buffer.
+ * @param[in] len       The length of the data buffer.
+ * @param[in] is_stderr Unused; SFTP does not use the stderr stream.
+ * @param[in] userdata  Pointer to the sftp_session handle.
+ *
+ * @return Number of bytes processed on success, `SSH_ERROR` on error.
  */
 int
 sftp_channel_default_data_callback(UNUSED_PARAM(ssh_session session),
diff --git a/src/socket.c b/src/socket.c
index e948dcfb..a2cd14b7 100644
--- a/src/socket.c
+++ b/src/socket.c
@@ -65,6 +65,9 @@ struct sockaddr_un {
  * @{
  */
 
+/** @internal
+ * @brief Represents the possible states of an SSH socket connection.
+ */
 enum ssh_socket_states_e {
 	SSH_SOCKET_NONE,
 	SSH_SOCKET_CONNECTING,
@@ -1063,12 +1066,26 @@ int ssh_socket_get_poll_flags(ssh_socket s)
 }
 
 #ifdef _WIN32
+/** @internal
+ * @brief Set a socket file descriptor to non-blocking mode.
+ *
+ * @param fd  The socket file descriptor to configure.
+ *
+ * @return  `SSH_OK` on success, `SSH_ERROR` on error.
+ */
 int ssh_socket_set_nonblocking(socket_t fd)
 {
     u_long nonblocking = 1;
     return ioctlsocket(fd, FIONBIO, &nonblocking);
 }
 
+/** @internal
+ * @brief Set a socket file descriptor to blocking mode.
+ *
+ * @param fd  The socket file descriptor to configure.
+ *
+ * @return  `SSH_OK` on success, `SSH_ERROR` on error.
+ */
 int ssh_socket_set_blocking(socket_t fd)
 {
     u_long nonblocking = 0;
@@ -1076,11 +1093,25 @@ int ssh_socket_set_blocking(socket_t fd)
 }
 
 #else /* _WIN32 */
+/** @internal
+ * @brief Set a socket file descriptor to non-blocking mode.
+ *
+ * @param fd  The socket file descriptor to configure.
+ *
+ * @return  `SSH_OK` on success, `SSH_ERROR` on error.
+ */
 int ssh_socket_set_nonblocking(socket_t fd)
 {
     return fcntl(fd, F_SETFL, O_NONBLOCK);
 }
 
+/** @internal
+ * @brief Set a socket file descriptor to blocking mode.
+ *
+ * @param fd  The socket file descriptor to configure.
+ *
+ * @return    0 on success, -1 on error.
+ */
 int ssh_socket_set_blocking(socket_t fd)
 {
     return fcntl(fd, F_SETFL, 0);
diff --git a/src/threads.c b/src/threads.c
index 8ff0278e..6da6fdc6 100644
--- a/src/threads.c
+++ b/src/threads.c
@@ -62,6 +62,9 @@ int ssh_threads_init(void)
     return rc;
 }
 
+/** @internal
+ * @brief Finalize and clean up the threading backend of the crypto libraries.
+ */
 void ssh_threads_finalize(void)
 {
     crypto_thread_finalize();
@@ -83,6 +86,12 @@ int ssh_threads_set_callbacks(struct ssh_threads_callbacks_struct *cb)
     return rc;
 }
 
+/** @internal
+ * @brief Get the type identifier of the currently active threading callbacks.
+ *
+ * @return  A string identifying the threading backend, or NULL if no
+ *          callbacks are registered.
+ */
 const char *ssh_threads_get_type(void)
 {
     if (user_callbacks != NULL) {