docs: add doxygen documentation and fix inconsistencies

- src/misc.c: added doxygen docs for ssh_get_local_username()
- src/auth.c: added doxygen docs for ssh_kbdint_new(), ssh_kbdint_free(), ssh_kbdint_clean()
- src/bind_config.c: fix @params -> @param, @returns -> @return
- src/bind.c, src/socket.c, src/threads.c: fix @returns -> @return
- include/libssh/callbacks.h: fix @returns -> @return

Signed-off-by: Emmanuel Ugwu <emmanuelugwu121@gmail.com>
Reviewed-by: Jakub Jelen <jjelen@redhat.com>

include/libssh/callbacks.h

@@ -522,7 +522,7 @@ typedef struct ssh_socket_callbacks_struct *ssh_socket_callbacks;
  *  verifies that the callback pointer exists
  * @param p callback pointer
  * @param c callback name
- * @returns nonzero if callback can be called
+ * @return nonzero if callback can be called
  */
 #define ssh_callbacks_exists(p,c) (\
   (p != NULL) && ( (char *)&((p)-> c) < (char *)(p) + (p)->size ) && \

src/auth.c

@@ -1835,6 +1835,14 @@ int ssh_userauth_agent_pubkey(ssh_session session,
     return rc;
 }
 
+/**
+ * @internal
+ *
+ * @brief  Allocates memory for keyboard interactive auth structure.
+ *
+ * @return A newly allocated ssh_kbdint structure `kbd` on success, NULL on failure.
+ *         The caller is responsible for freeing allocated memory.
+ */
 ssh_kbdint ssh_kbdint_new(void)
 {
     ssh_kbdint kbd;
@@ -1847,7 +1855,11 @@ ssh_kbdint ssh_kbdint_new(void)
     return kbd;
 }
 
-
+/**
+ * @brief Deallocate memory for keyboard interactive auth structure.
+ *
+ * @param[in] kbd   The keyboard interactive structure to free.
+ */
 void ssh_kbdint_free(ssh_kbdint kbd)
 {
     size_t i, n;
@@ -1885,6 +1897,14 @@ void ssh_kbdint_free(ssh_kbdint kbd)
     SAFE_FREE(kbd);
 }
 
+/**
+ * @brief Clean a keyboard interactive auth structure.
+ *
+ * Clears structure's fields and resets nanswers and nprompts to 0, allowing
+ * reuse.
+ *
+ * @param[in] kbd The keyboard interactive struct to clean
+ */
 void ssh_kbdint_clean(ssh_kbdint kbd)
 {
     size_t i, n;

src/bind.c

@@ -327,7 +327,7 @@ static int ssh_bind_poll_callback(ssh_poll_handle sshpoll, socket_t fd, int reve
 /** @internal
  * @brief returns the current poll handle, or creates it
  * @param sshbind the ssh_bind object
- * @returns a ssh_poll handle suitable for operation
+ * @return a ssh_poll handle suitable for operation
  */
 ssh_poll_handle ssh_bind_get_poll(ssh_bind sshbind)
 {

src/bind_config.c

@@ -680,8 +680,8 @@ int ssh_bind_config_parse_file(ssh_bind bind, const char *filename)
  * @brief Parse configuration string and set the options to the given bind
  * session
  *
- * @params[in] bind      The ssh bind session
- * @params[in] input     Null terminated string containing the configuration
+ * @param[in] bind      The ssh bind session
+ * @param[in] input     Null terminated string containing the configuration
  *
  * @warning Options set via this function may be overridden if a configuration
  *          file is parsed afterwards (e.g., by an implicit call to
@@ -690,7 +690,7 @@ int ssh_bind_config_parse_file(ssh_bind bind, const char *filename)
  *          It is the caller’s responsibility to ensure the correct order of
  *          API calls if explicit options must take precedence.
  *
- * @returns    SSH_OK on successful parsing the configuration string,
+ * @return    SSH_OK on successful parsing the configuration string,
  *             SSH_ERROR on error
  */
 int ssh_bind_config_parse_string(ssh_bind bind, const char *input)

src/misc.c

@@ -208,6 +208,12 @@ struct tm *ssh_localtime(const time_t *timer, struct tm *result)
     return result;
 }
 
+/**
+ * @brief  Get username from the calling process.
+ *
+ * @return An allocated string with the user on success, NULL on failure. The
+ * caller is responsible for freeing returned string.
+ */
 char *ssh_get_local_username(void)
 {
     DWORD size = 0;
@@ -357,6 +363,12 @@ int ssh_dir_writeable(const char *path)
     return 0;
 }
 
+/**
+ * @brief  Get username from the calling process.
+ *
+ * @return An allocated string with the name on success, NULL on failure. The
+ * caller is responsible for freeing returned string.
+ */
 char *ssh_get_local_username(void)
 {
     struct passwd pwd;

src/socket.c

@@ -444,7 +444,8 @@ int ssh_socket_pollcallback(struct ssh_poll_handle_struct *p,
 /** @internal
  * @brief returns the poll handle corresponding to the socket,
  * creates it if it does not exist.
- * @returns allocated and initialized ssh_poll_handle object
+ *
+ * @return allocated and initialized ssh_poll_handle object
  */
 ssh_poll_handle ssh_socket_get_poll_handle(ssh_socket s)
 {

src/threads.c

@@ -38,7 +38,6 @@ static struct ssh_threads_callbacks_struct *user_callbacks = NULL;
 /** @internal
  * @brief inits the threading with the backend cryptographic libraries
  */
-
 int ssh_threads_init(void)
 {
     static int threads_initialized = 0;