diff --git a/libssh/messages.c b/libssh/messages.c
index 1a3e4ffe..c6cec583 100644
--- a/libssh/messages.c
+++ b/libssh/messages.c
@@ -850,11 +850,15 @@ void ssh_message_free(ssh_message msg){
   SAFE_FREE(msg);
 }
 
-/** \internal
- * \brief handle various SSH request messages and stack them for callback
- * \param session SSH session
- * \param type packet type
- * \returns nothing
+/** @internal
+ * @brief handle various SSH request messages and stack them for callback.
+ * @param session SSH session.
+ * @param user user provided value.
+ * @param type packet type.
+ * @param packet buffer.
+ * @return SSH_PACKET_USED if a message has been created.
+ * @return SSH_PACKET_NOT_USED if the packet could not be used to create a
+ * message.
  */
 int message_handle(ssh_session session, void *user, uint8_t type, ssh_buffer packet){
   ssh_message msg=ssh_message_retrieve(session,type);
diff --git a/libssh/socket.c b/libssh/socket.c
index a1a0e2cd..d5df4c39 100644
--- a/libssh/socket.c
+++ b/libssh/socket.c
@@ -123,8 +123,9 @@ ssh_socket ssh_socket_new(ssh_session session) {
 /**
  * @internal
  * @brief the socket callbacks, i.e. callbacks to be called
- * upon a socket event
- * @param callbacks a ssh_socket_callback object reference
+ * upon a socket event.
+ * @param s socket to set callbacks on.
+ * @param callbacks a ssh_socket_callback object reference.
  */
 
 void ssh_socket_set_callbacks(ssh_socket s, ssh_socket_callbacks callbacks){
@@ -770,14 +771,15 @@ int ssh_socket_get_status(ssh_socket s) {
  * @internal
  * @brief Launches a socket connection
  * If a the socket connected callback has been defined and
- * a poll object exists, this call will be non blocking
- * @param host hostname or ip address to connect to
- * @param port port number to connect to
- * @param bind_addr address to bind to, or NULL for default
- * @returns SSH_OK socket is being connected
- * @returns SSH_ERROR error while connecting to remote host
+ * a poll object exists, this call will be non blocking.
+ * @param s    socket to connect.
+ * @param host hostname or ip address to connect to.
+ * @param port port number to connect to.
+ * @param bind_addr address to bind to, or NULL for default.
+ * @returns SSH_OK socket is being connected.
+ * @returns SSH_ERROR error while connecting to remote host.
  * @bug It only tries connecting to one of the available AI's
- * which is problematic for hosts having DNS fail-over
+ * which is problematic for hosts having DNS fail-over.
  */
 
 int ssh_socket_connect(ssh_socket s, const char *host, int port, const char *bind_addr){