doxygen fixes. Mostly typos and some comments.

sftp must be fully documented !


git-svn-id: svn+ssh://svn.berlios.de/svnroot/repos/libssh/trunk@187 7dcaeef0-15fb-0310-b436-a5af3365683c

libssh/auth1.c

@@ -112,6 +112,9 @@ int ssh_userauth_offer_pubkey(SSH_SESSION *session, char *username,int type, STR
     return err;
 }
 */
+/** \internal
+ * \todo implement ssh1 public key
+ */
 int ssh_userauth1_offer_pubkey(SSH_SESSION *session, char *username, int type,
         STRING *pubkey){
     return SSH_AUTH_DENIED;

libssh/base64.c

@@ -44,8 +44,12 @@ static int get_equals(char *string);
 
 /* first part : base 64 to binary */
 
-/* base64_to_bin translates a base64 string into a binary one. important, if something went wrong (ie incorrect char)*/
+/** \brief base64_to_bin translates a base64 string into a binary one. important,
-/* it returns NULL */
+ * \returns NULL if something went wrong (ie incorrect char)
+ * \returns BUFFER containing the decoded string
+ * \internal
+ */
+
 BUFFER *base64_to_bin(char *source){
     int len;
     int equals;
@@ -192,7 +196,10 @@ static void _bin_to_base64(unsigned char *dest, unsigned char source[3], int len
         break;
     }
 }
-
+/** \brief Converts binary data to a base64 string
+ * \returns the converted string
+ * \internal
+ */
 unsigned char *bin_to_base64(unsigned char *source, int len){
     int flen=len + (3 - (len %3)); /* round to upper 3 multiple */
     unsigned char *buffer;

libssh/buffer.c

@@ -39,7 +39,7 @@ BUFFER *buffer_new(){
     return buffer;
 }
 
-/** \brief desallocate a buffer
+/** \brief deallocate a buffer
  * \param buffer buffer to free
  */
 void buffer_free(BUFFER *buffer){
@@ -90,19 +90,36 @@ void buffer_add_data(BUFFER *buffer,const void *data,int len){
     buffer->used+=len;
 }
 
+/** \internal
+ * \brief add a SSH string to the tail of buffer
+ * \param buffer buffer
+ * \param string SSH String to add
+ */
 void buffer_add_ssh_string(BUFFER *buffer,STRING *string){
     u32 len=ntohl(string->size);
     buffer_add_data(buffer,string,len+sizeof(u32));
 }
-
+/** \internal
+ * \brief add a 32 bits unsigned integer to the tail of buffer
+ * \param buffer buffer
+ * \param data 32 bits integer
+ */
 void buffer_add_u32(BUFFER *buffer,u32 data){
     buffer_add_data(buffer,&data,sizeof(data));
 }
-
+/** \internal
+ * \brief add a 64 bits unsigned integer to the tail of buffer
+ * \param buffer buffer
+ * \param data 64 bits integer
+ */
 void buffer_add_u64(BUFFER *buffer,u64 data){
     buffer_add_data(buffer,&data,sizeof(data));
 }
-
+/** \internal
+ * \brief add a 8 bits unsigned integer to the tail of buffer
+ * \param buffer buffer
+ * \param data 8 bits integer
+ */
 void buffer_add_u8(BUFFER *buffer,u8 data){
     buffer_add_data(buffer,&data,sizeof(u8));
 }
@@ -203,6 +220,14 @@ int buffer_pass_bytes_end(BUFFER *buffer,int len){
     return len;
 }
 
+/** \internal
+ * \brief gets remaining data out of the buffer. Adjust the read pointer.
+ * \param buffer Buffer to read
+ * \param data data buffer where to store the data
+ * \param len length to read from the buffer
+ * \returns 0 if there is not enough data in buffer
+ * \returns len otherwise.
+ */
 int buffer_get_data(BUFFER *buffer, void *data, int len){
     if(buffer->pos+len>buffer->used)
         return 0;  /*no enough data in buffer */
@@ -210,19 +235,43 @@ int buffer_get_data(BUFFER *buffer, void *data, int len){
     buffer->pos+=len;
     return len;   /* no yet support for partial reads (is it really needed ?? ) */
 }
-
+/** \internal
+ * \brief gets a 8 bits unsigned int out of the buffer. Adjusts the read pointer.
+ * \param buffer Buffer to read
+ * \param data pointer to a u8 where to store the data
+ * \returns 0 if there is not enough data in buffer
+ * \returns 1 otherwise.
+ */
 int buffer_get_u8(BUFFER *buffer, u8 *data){
     return buffer_get_data(buffer,data,sizeof(u8));
 }
 
+/** \internal
+ * \brief gets a 32 bits unsigned int out of the buffer. Adjusts the read pointer.
+ * \param buffer Buffer to read
+ * \param data pointer to a u32 where to store the data
+ * \returns 0 if there is not enough data in buffer
+ * \returns 4 otherwise.
+ */
 int buffer_get_u32(BUFFER *buffer, u32 *data){
     return buffer_get_data(buffer,data,sizeof(u32));
 }
-
+/** \internal
+ * \brief gets a 64 bits unsigned int out of the buffer. Adjusts the read pointer.
+ * \param buffer Buffer to read
+ * \param data pointer to a u64 where to store the data
+ * \returns 0 if there is not enough data in buffer
+ * \returns 8 otherwise.
+ */
 int buffer_get_u64(BUFFER *buffer, u64 *data){
     return buffer_get_data(buffer,data,sizeof(u64));
 }
-
+/** \internal
+ * \brief gets a SSH String out of the buffer. Adjusts the read pointer.
+ * \param buffer Buffer to read
+ * \returns The SSH String read
+ * \returns NULL otherwise.
+ */
 STRING *buffer_get_ssh_string(BUFFER *buffer){
     u32 stringlen;
     u32 hostlen;
@@ -241,8 +290,14 @@ STRING *buffer_get_ssh_string(BUFFER *buffer){
         }
     return str;
 }
+/** \internal
+ * \brief gets a mpint out of the buffer. Adjusts the read pointer.
+ * SSH-1 only
+ * \param buffer Buffer to read
+ * \returns the SSH String containing the mpint
+ * \returns NULL otherwise
+ */
 
-/* this one is SSH-1 only */
 STRING *buffer_get_mpint(BUFFER *buffer){
     u16 bits;
     u32 len;

libssh/channels.c

@@ -382,7 +382,7 @@ void channel_default_bufferize(CHANNEL *channel, void *data, int len, int is_std
     }
 }
 
-/** \brief open a session channel (suited for a shell. Not tcp)
+/** \brief open a session channel (suited for a shell. Not tcp Forwarding)
  * \param channel an allocated channel (see channel_new())
  * \return SSH_OK on success\n
  * SSH_ERROR on error

libssh/client.c

@@ -87,10 +87,9 @@ int ssh_analyze_banner(SSH_SESSION *session, int *ssh1, int *ssh2){
     return 0;
 }
 
-/* ssh_send_banner sends a SSH banner to the server */
+/** \internal
-/* TODO select a banner compatible with server version */
+ *  \brief ssh_send_banner sends a SSH banner to the server
-/* switch SSH1/1.5/2 */
+ */
-/* and quit when the server is SSH1 only */
 
 int ssh_send_banner(SSH_SESSION *session,int server){
      char *banner;
@@ -356,7 +355,7 @@ int ssh_connect(SSH_SESSION *session){
 }
 
 /** this is the banner showing a disclaimer to users who log in,
- * typicaly their right or the fact that they will be monitored
+ * typically their right or the fact that they will be monitored
  * \brief get the issue banner from the server
  * \param session ssh session
  * \return NULL if there is no issue banner, else a string containing it.

libssh/connect.c

@@ -136,9 +136,12 @@ int ssh_connect_ai_timeout(SSH_SESSION *session, const char *host, int port, str
     return s;
 }
 
-/* connect_host connects to an IPv4 (or IPv6) host */
+/** \internal
-/* specified by its IP address or hostname. */
+ * \brief connect_host connects to an IPv4 (or IPv6) host
-/* output is the file descriptor, <0 if failed. */
+ * specified by its IP address or hostname.
+ * \returns file descriptor
+ * \returns less than 0 value
+ */
 
 socket_t ssh_connect_host(SSH_SESSION *session, const char *host, const char
         *bind_addr, int port,long timeout, long usec){

libssh/init.c

@@ -25,7 +25,14 @@ MA 02111-1307, USA. */
 #ifdef _WIN32
 #include <winsock2.h>
 #endif
-
+/**
+ * \addtogroup ssh_session
+ * @{
+ */
+/**
+ * \brief finalize and cleanup all libssh and cryptographic data structures
+ * \returns 0
+ */
 int ssh_finalize()
 {
   ssh_crypto_finalize();
@@ -39,3 +46,7 @@ int ssh_finalize()
 #endif
   return 0;
 }
+
+/**
+ * @}
+ */

libssh/keyfiles.c

@@ -623,7 +623,7 @@ PRIVATE_KEY  *_privatekey_from_file(void *session,char *filename,int type){
     return privkey;
 }
 
-/** \brief Desallocate a private key
+/** \brief deallocate a private key
  * \param prv a PRIVATE_KEY object
  */
 void private_key_free(PRIVATE_KEY *prv){

libssh/messages.c

@@ -18,13 +18,16 @@ You should have received a copy of the GNU Lesser General Public License
 along with the SSH Library; see the file COPYING.  If not, write to
 the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 MA 02111-1307, USA. */
-
+/** \defgroup ssh_messages SSH Messages
-/* this file contains the Message parsing utilities for server programs using 
+ * this file contains the Message parsing utilities for server programs using
  * libssh. The main loop of the program will call ssh_message_get(session) to
  * get messages as they come. they are not 1-1 with the protocol messages.
  * then, the user will know what kind of a message it is and use the appropriate
  * functions to handle it (or use the default handlers if she doesn't know what to
- * do */
+ * do
+ * \addtogroup ssh_messages
+ * @{
+ */
 
 #include <string.h>
 #include <stdlib.h>
@@ -444,3 +447,5 @@ void ssh_message_free(SSH_MESSAGE *msg){
     }
     memset(msg,0,sizeof(*msg));
 }
+/** @}
+ */

libssh/server.c

@@ -19,8 +19,11 @@ along with the SSH Library; see the file COPYING.  If not, write to
 the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 MA 02111-1307, USA. */
 
-/* from times to times, you need to serve your friends */
+/**
-/* and, perhaps, ssh connections. */
+ * \defgroup ssh_server SSH Server
+ * \addtogroup ssh_server
+ * @{
+ */
 
 #include <fcntl.h>
 #include <unistd.h>
@@ -296,4 +299,5 @@ int ssh_accept(SSH_SESSION *session){
     session->connected=1;
     return 0;
 }
-
+/** @}
+ */

libssh/sftp.c

@@ -23,6 +23,7 @@ MA 02111-1307, USA. */
 
 /** \defgroup ssh_sftp SFTP functions
  * \brief SFTP handling functions
+ * \bug Write docs !
  */
 /** \addtogroup ssh_sftp
  * @{ */

libssh/string.c

@@ -89,6 +89,9 @@ STRING *string_copy(STRING *str){
     return ret;
 }
 
+/** \brief destroy data in a string so it couldn't appear in a core dump
+ * \param s string to burn
+ */
 void string_burn(STRING *s){
     memset(s->string,'X',string_len(s));
 }
@@ -98,7 +101,7 @@ void *string_data(STRING *s){
 }
 
 /**
- * \brief desallocate a STRING object
+ * \brief deallocate a STRING object
  * \param s String to delete
  */
 void string_free(STRING *s){