good work tonight. Made documentation for authentication, channels, buffers, errors

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

libssh/buffer.c

@@ -24,12 +24,27 @@ MA 02111-1307, USA. */
 #include <string.h>
 #include <netdb.h>
 #include "libssh/priv.h"
+
+/** defgroup ssh_buffer
+ * \brief buffer handling
+ */
+
+/** \addtogroup ssh_buffer
+ * @{
+ */
+
+/** \brief creates a new buffer
+ * \return a new initialized buffer
+ */
 BUFFER *buffer_new(){
     BUFFER *buffer=malloc(sizeof(BUFFER));
     memset(buffer,0,sizeof(BUFFER));
     return buffer;
     }
 
+/** \brief desallocate a buffer
+ * \param buffer buffer to free
+ */
 void buffer_free(BUFFER *buffer){
 //    printf("buffer %p : free(%p);\n",buffer,buffer->data);
     if(buffer->data){
@@ -40,6 +55,10 @@ void buffer_free(BUFFER *buffer){
     free(buffer);
     }
 
+/* \internal
+ * \brief reinitialize a buffer
+ * \param buffer buffer
+ */
 void buffer_reinit(BUFFER *buffer){
     memset(buffer->data,0,buffer->used);
     buffer->used=0;
@@ -53,7 +72,12 @@ static void realloc_buffer(BUFFER *buffer,int needed){
 //    printf("%p\n",buffer->data);
     buffer->allocated=needed;
 }
-
+/** \internal
+ * \brief add data at tail of the buffer
+ * \param buffer buffer
+ * \param data data pointer
+ * \param len length of data
+ */
 void buffer_add_data(BUFFER *buffer,void *data,int len){
     if(buffer->allocated < buffer->used+len)
         realloc_buffer(buffer,buffer->used+len);
@@ -78,6 +102,12 @@ void buffer_add_u8(BUFFER *buffer,u8 data){
     buffer_add_data(buffer,&data,sizeof(u8));
 }
 
+/** \internal
+ * \brief add data at head of a buffer
+ * \param buffer buffer
+ * \param data data to add
+ * \param len length of data
+ */
 void buffer_add_data_begin(BUFFER *buffer, void *data, int len){
     if(buffer->allocated < buffer->used + len)
         realloc_buffer(buffer,buffer->used+len);
@@ -86,26 +116,63 @@ void buffer_add_data_begin(BUFFER *buffer, void *data, int len){
     buffer->used+=len;
 }
 
+/** \internal
+ * \brief append data from a buffer to tail of another
+ * \param buffer destination buffer
+ * \param source source buffer. Doesn't take position in buffer into account
+ */
 void buffer_add_buffer(BUFFER *buffer, BUFFER *source){
     buffer_add_data(buffer,buffer_get(source),buffer_get_len(source));
 }
 
+/** \brief get a pointer on the head of the buffer
+ * \param buffer buffer
+ * \return data pointer on the head. Doesn't take position into account.
+ * \warning don't expect data to be nul-terminated
+ * \see buffer_get_rest()
+ * \see buffer_get_len()
+ */
 void *buffer_get(BUFFER *buffer){
     return buffer->data;
 }
 
+/** \internal
+ * \brief get a pointer to head of the buffer at current position
+ * \param buffer buffer
+ * \return pointer to the data from current position
+ * \see buffer_get_rest_len()
+ * \see buffer_get()
+ */
 void *buffer_get_rest(BUFFER *buffer){
     return buffer->data+buffer->pos;
 }
 
+/** \brief get length of the buffer, not counting position
+ * \param buffer
+ * \return length of the buffer
+ * \see buffer_get()
+ */
 int buffer_get_len(BUFFER *buffer){
     return buffer->used;
 }
 
+/** \internal
+ *  \brief get length of the buffer from the current position
+ * \param buffer
+ * \return length of the buffer
+ * \see buffer_get_rest()
+ */
 int buffer_get_rest_len(BUFFER *buffer){
     return buffer->used - buffer->pos;
 }
 
+/** \internal
+ * has effect to "eat" bytes at head of the buffer 
+ * \brief advance the position in the buffer
+ * \param buffer buffer
+ * \param len number of bytes to eat
+ * \return new size of the buffer
+ */
 int buffer_pass_bytes(BUFFER *buffer,int len){
     if(buffer->used < buffer->pos+len)
         return 0;
@@ -118,6 +185,12 @@ int buffer_pass_bytes(BUFFER *buffer,int len){
     return len;
 }
 
+/** \internal
+ * \brief cut the end of the buffer
+ * \param buffer buffer
+ * \param len number of bytes to remove from tail
+ * \return new size of the buffer
+ */
 int buffer_pass_bytes_end(BUFFER *buffer,int len){
     if(buffer->used < buffer->pos + len)
         return 0;
@@ -182,4 +255,5 @@ STRING *buffer_get_mpint(BUFFER *buffer){
     }
     return str;
 }
+/** @} */