Improve the session documentation.

libssh/init.c

@@ -31,17 +31,20 @@
 #endif
 
 /**
- * \addtogroup ssh_session
+ * @defgroup libssh The libssh API
+ *
+ * This is a library implementing the SSH protocols.
+ *
  * @{
  */
 
 /**
- * @brief initialize global cryptographic data structures.
+ * @brief Initialize global cryptographic data structures.
  *
  * This function should only be called once, at the beginning of the program, in
  * the main thread. It may be omitted if your program is not multithreaded.
  *
- * @returns 0
+ * @returns             0 on success, -1 if an error occured.
  */
 int ssh_init(void) {
   if(ssh_crypto_init())
@@ -59,7 +62,8 @@ int ssh_init(void) {
  *
  * This function should only be called once, at the end of the program!
  *
- * @returns -1 in case of error
+ * @returns             0 on succes, -1 if an error occured.
+ *
    @returns 0 otherwise
  */
 int ssh_finalize(void) {
@@ -77,7 +81,6 @@ int ssh_finalize(void) {
   return 0;
 }
 
-/**
+/* @} */
- * @}
+
- */
+/* vim: set ts=4 sw=4 et cindent: */
-/* vim: set ts=2 sw=2 et cindent: */

libssh/session.c

@@ -38,14 +38,19 @@
 
 #define FIRST_CHANNEL 42 // why not ? it helps to find bugs.
 
-/** \defgroup ssh_session SSH Session
+/**
- * \brief functions that manage a session
+ * @defgroup libssh_session The SSH session functions.
+ * @ingroup libssh
+ *
+ * Functions that manage a session.
+ *
+ * @{
  */
-/** \addtogroup ssh_session
- * @{ */
 
-/** \brief creates a new ssh session
+/**
- * \returns new ssh_session pointer
+ * @brief Create a new ssh session.
+ *
+ * @returns             A new ssh_session pointer, NULL on error.
  */
 ssh_session ssh_new(void) {
   ssh_session session;
@@ -106,7 +111,10 @@ err:
 }
 
 /**
- * @brief deallocate a session handle
+ * @brief Deallocate a SSH session handle.
+ *
+ * @param[in] session   The SSH session to free.
+ *
  * @see ssh_disconnect()
  * @see ssh_new()
  */
@@ -183,9 +191,12 @@ void ssh_free(ssh_session session) {
   SAFE_FREE(session);
 }
 
-/** \brief disconnect impolitely from remote host by closing the socket.
+/**
+ * @brief Disconnect impolitely from a remote host by closing the socket.
+ *
  * Suitable if you forked and want to destroy this session.
- * \param session current ssh session
+ *
+ * @param[in]  session  The SSH session to disconnect.
  */
 void ssh_silent_disconnect(ssh_session session) {
   enter_function();
@@ -200,9 +211,13 @@ void ssh_silent_disconnect(ssh_session session) {
   leave_function();
 }
 
-/** \brief set the session in blocking/nonblocking mode
+/**
- * \param session ssh session
+ * @brief Set the session in blocking/nonblocking mode.
- * \param blocking zero for nonblocking mode
+ *
+ * @param[in]  session  The ssh session to change.
+ *
+ * @param[in]  blocking Zero for nonblocking mode.
+ *
  * \bug nonblocking code is in development and won't work as expected
  */
 void ssh_set_blocking(ssh_session session, int blocking) {
@@ -213,12 +228,15 @@ void ssh_set_blocking(ssh_session session, int blocking) {
   session->blocking = blocking ? 1 : 0;
 }
 
-/** In case you'd need the file descriptor of the connection
+/**
- * to the server/client
+ * @brief Get the fd of a connection.
- * \brief recover the fd of connection
+ *
- * \param session ssh session
+ * In case you'd need the file descriptor of the connection to the server/client.
- * \return file descriptor of the connection, or -1 if it is
+ *
- * not connected
+ * @param[in] session   The ssh session to use.
+ *
+ * @return              The file descriptor of the connection, or -1 if it is
+ *                      not connected
  */
 socket_t ssh_get_fd(ssh_session session) {
   if (session == NULL) {
@@ -228,8 +246,11 @@ socket_t ssh_get_fd(ssh_session session) {
   return ssh_socket_get_fd(session->socket);
 }
 
-/** \brief say to the session it has data to read on the file descriptor without blocking
+/**
- * \param session ssh session
+ * @brief Tell the session it has data to read on the file descriptor without
+ * blocking.
+ *
+ * @param[in] session   The ssh session to use.
  */
 void ssh_set_fd_toread(ssh_session session) {
   if (session == NULL) {
@@ -239,8 +260,10 @@ void ssh_set_fd_toread(ssh_session session) {
   ssh_socket_set_toread(session->socket);
 }
 
-/** \brief say the session it may write to the file descriptor without blocking
+/**
- * \param session ssh session
+ * @brief Tell the session it may write to the file descriptor without blocking.
+ *
+ * @param[in] session   The ssh session to use.
  */
 void ssh_set_fd_towrite(ssh_session session) {
   if (session == NULL) {
@@ -250,8 +273,10 @@ void ssh_set_fd_towrite(ssh_session session) {
   ssh_socket_set_towrite(session->socket);
 }
 
-/** \brief say the session it has an exception to catch on the file descriptor
+/**
- * \param session ssh session
+ * @brief Tell the session it has an exception to catch on the file descriptor.
+ *
+ * \param[in] session   The ssh session to use.
  */
 void ssh_set_fd_except(ssh_session session) {
   if (session == NULL) {
@@ -261,15 +286,22 @@ void ssh_set_fd_except(ssh_session session) {
   ssh_socket_set_except(session->socket);
 }
 
-/** @internal
+/**
- * @brief polls the current session for an event and call the
+ * @internal
- * appropriate callbacks. Will block until one event happens.
+ *
- * @param session session handle.
+ * @brief Poll the current session for an event and call the appropriate
- * @param timeout An upper limit on the time for which
+ * callbacks.
- * ssh_handle_packets() will block, in milliseconds.
+ *
- * Specifying a negative value means an infinite timeout.
+ * This will block until one event happens.
- * This parameter is passed to the poll() function.
+ *
- * @return SSH_OK if there are no error, SSH_ERROR otherwise.
+ * @param[in] session   The session handle to use.
+ *
+ * @param[in] timeout   Set an upper limit on the time for which this function
+ *                      will block, in milliseconds. Specifying a negative value
+ *                      means an infinite timeout. This parameter is passed to
+ *                      the poll() function.
+ *
+ * @return              SSH_OK on success, SSH_ERROR otherwise.
  */
 int ssh_handle_packets(ssh_session session, int timeout) {
 	ssh_poll_handle spoll;
@@ -323,10 +355,16 @@ int ssh_get_status(ssh_session session) {
   return r;
 }
 
-/** \brief get the disconnect message from the server
+/**
- * \param session ssh session
+ * @brief Get the disconnect message from the server.
- * \return message sent by the server along with the disconnect, or NULL in which case the reason of the disconnect may be found with ssh_get_error.
+ *
- * \see ssh_get_error()
+ * @param[in] session   The ssh session to use.
+ *
+ * @return              The message sent by the server along with the
+ *                      disconnect, or NULL in which case the reason of the
+ *                      disconnect may be found with ssh_get_error.
+ *
+ * @see ssh_get_error()
  */
 const char *ssh_get_disconnect_message(ssh_session session) {
   if (session == NULL) {
@@ -366,7 +404,8 @@ int ssh_get_version(ssh_session session) {
 
 /**
  * @internal
- * @brief handles a SSH_DISCONNECT packet
+ *
+ * @brief Handle a SSH_DISCONNECT packet.
  */
 SSH_PACKET_CALLBACK(ssh_packet_disconnect_callback){
 	uint32_t code;
@@ -395,7 +434,8 @@ SSH_PACKET_CALLBACK(ssh_packet_disconnect_callback){
 
 /**
  * @internal
- * @brief handles a SSH_IGNORE and SSH_DEBUG packet
+ *
+ * @brief Handle a SSH_IGNORE and SSH_DEBUG packet.
  */
 SSH_PACKET_CALLBACK(ssh_packet_ignore_callback){
 	(void)user;
@@ -405,5 +445,7 @@ SSH_PACKET_CALLBACK(ssh_packet_ignore_callback){
 	/* TODO: handle a graceful disconnect */
 	return SSH_PACKET_USED;
 }
-/** @} */
+
+/* @} */
+
 /* vim: set ts=2 sw=2 et cindent: */