Fixed the documentation of buffer.c

1 files changed, 237 insertions, 121 deletions

diff --git a/libssh/buffer.c b/libssh/buffer.c
index 1a014a58..0dd65843 100644
--- a/libssh/buffer.c
+++ b/libssh/buffer.c
@@ -30,19 +30,25 @@
 
 #include "libssh/priv.h"
 #include "libssh/buffer.h"
-/** \defgroup ssh_buffer SSH Buffers
- * \brief buffer handling
- */
 
-/** \addtogroup ssh_buffer
+/**
+ * @defgroup libssh_buffer The SSH buffer functions.
+ * @ingroup libssh
+ *
+ * Functions to handle SSH buffers.
+ *
  * @{
  */
 
-/** \brief checks that preconditions and postconditions are valid
- * \internal
- */
 
 #ifdef DEBUG_BUFFER
+/**
+ * @internal
+ *
+ * @brief Check that preconditions and postconditions are valid.
+ *
+ * @param[in]  buf      The buffer to check.
+ */
 static void buffer_verify(struct buffer_struct *buf){
   int doabort=0;
   if(buf->data == NULL)
@@ -67,8 +73,10 @@ static void buffer_verify(struct buffer_struct *buf){
 #define buffer_verify(x)
 #endif
 
-/** \brief creates a new buffer
- * \return a new initialized buffer, NULL on error.
+/**
+ * @brief Create a new SSH buffer.
+ *
+ * @return A newly initialized SSH buffer, NULL on error.
  */
 struct ssh_buffer_struct *buffer_new(void) {
   struct ssh_buffer_struct *buf = malloc(sizeof(struct ssh_buffer_struct));
@@ -81,8 +89,10 @@ struct ssh_buffer_struct *buffer_new(void) {
   return buf;
 }
 
-/** \brief deallocate a buffer
- * \param buffer buffer to free
+/**
+ * @brief Deallocate a SSH buffer.
+ *
+ * \param[in]  buffer   The buffer to free.
  */
 void buffer_free(struct ssh_buffer_struct *buffer) {
   if (buffer == NULL) {
@@ -118,10 +128,14 @@ static int realloc_buffer(struct ssh_buffer_struct *buffer, int needed) {
   return 0;
 }
 
-/* \internal
- * \brief reinitialize a buffer
- * \param buffer buffer
- * \return 0 on success, < 0 on error
+/**
+ * @internal
+ *
+ * @brief Reinitialize a SSH buffer.
+ *
+ * @param[in]  buffer   The buffer to reinitialize.
+ *
+ * @return              0 on success, < 0 on error.
  */
 int buffer_reinit(struct ssh_buffer_struct *buffer) {
   buffer_verify(buffer);
@@ -137,11 +151,18 @@ int buffer_reinit(struct ssh_buffer_struct *buffer) {
   return 0;
 }
 
-/** \internal
- * \brief add data at tail of the buffer
- * \param buffer buffer
- * \param data data pointer
- * \param len length of data
+/**
+ * @internal
+ *
+ * @brief Add data at the tail of a buffer.
+ *
+ * @param[in]  buffer   The buffer to add the data.
+ *
+ * @param[in]  data     A pointer to the data to add.
+ *
+ * @param[in]  len      The length of the data to add.
+ *
+ * @return              0 on success, < 0 on error.
  */
 int buffer_add_data(struct ssh_buffer_struct *buffer, const void *data, uint32_t len) {
   buffer_verify(buffer);
@@ -157,11 +178,16 @@ int buffer_add_data(struct ssh_buffer_struct *buffer, const void *data, uint32_t
   return 0;
 }
 
-/** \internal
- * \brief add a SSH string to the tail of buffer
- * \param buffer buffer
- * \param string SSH String to add
- * \return 0 on success, -1 on error.
+/**
+ * @internal
+ *
+ * @brief Add a SSH string to the tail of a buffer.
+ *
+ * @param[in]  buffer   The buffer to add the string.
+ *
+ * @param[in]  string   The SSH String to add.
+ *
+ * @return              0 on success, < 0 on error.
  */
 int buffer_add_ssh_string(struct ssh_buffer_struct *buffer,
     struct ssh_string_struct *string) {
@@ -175,11 +201,16 @@ int buffer_add_ssh_string(struct ssh_buffer_struct *buffer,
   return 0;
 }
 
-/** \internal
- * \brief add a 32 bits unsigned integer to the tail of buffer
- * \param buffer buffer
- * \param data 32 bits integer
- * \return 0 on success, -1 on error.
+/**
+ * @internal
+ *
+ * @brief Add a 32 bits unsigned integer to the tail of a buffer.
+ *
+ * @param[in]  buffer   The buffer to add the integer.
+ *
+ * @param[in]  data     The 32 bits integer to add.
+ *
+ * @return              0 on success, -1 on error.
  */
 int buffer_add_u32(struct ssh_buffer_struct *buffer,uint32_t data){
   if (buffer_add_data(buffer, &data, sizeof(data)) < 0) {
@@ -189,11 +220,16 @@ int buffer_add_u32(struct ssh_buffer_struct *buffer,uint32_t data){
   return 0;
 }
 
-/** \internal
- * \brief add a 16 bits unsigned integer to the tail of buffer
- * \param buffer buffer
- * \param data 16 bits integer
- * \return 0 on success, -1 on error.
+/**
+ * @internal
+ *
+ * @brief Add a 16 bits unsigned integer to the tail of a buffer.
+ *
+ * @param[in]  buffer   The buffer to add the integer.
+ *
+ * @param[in]  data     The 16 bits integer to add.
+ *
+ * @return              0 on success, -1 on error.
  */
 int buffer_add_u16(struct ssh_buffer_struct *buffer,uint16_t data){
   if (buffer_add_data(buffer, &data, sizeof(data)) < 0) {
@@ -203,11 +239,16 @@ int buffer_add_u16(struct ssh_buffer_struct *buffer,uint16_t data){
   return 0;
 }
 
-/** \internal
- * \brief add a 64 bits unsigned integer to the tail of buffer
- * \param buffer buffer
- * \param data 64 bits integer
- * \return 0 on success, -1 on error.
+/**
+ * @internal
+ *
+ * @brief Add a 64 bits unsigned integer to the tail of a buffer.
+ *
+ * @param[in]  buffer   The buffer to add the integer.
+ *
+ * @param[in]  data     The 64 bits integer to add.
+ *
+ * @return              0 on success, -1 on error.
  */
 int buffer_add_u64(struct ssh_buffer_struct *buffer, uint64_t data){
   if (buffer_add_data(buffer, &data, sizeof(data)) < 0) {
@@ -216,11 +257,17 @@ int buffer_add_u64(struct ssh_buffer_struct *buffer, uint64_t data){
 
   return 0;
 }
-/** \internal
- * \brief add a 8 bits unsigned integer to the tail of buffer
- * \param buffer buffer
- * \param data 8 bits integer
- * \return 0 on success, -1 on error.
+
+/**
+ * @internal
+ *
+ * @brief Add a 8 bits unsigned integer to the tail of a buffer.
+ *
+ * @param[in]  buffer   The buffer to add the integer.
+ *
+ * @param[in]  data     The 8 bits integer to add.
+ *
+ * @return              0 on success, -1 on error.
  */
 int buffer_add_u8(struct ssh_buffer_struct *buffer,uint8_t data){
   if (buffer_add_data(buffer, &data, sizeof(uint8_t)) < 0) {
@@ -230,12 +277,18 @@ int buffer_add_u8(struct ssh_buffer_struct *buffer,uint8_t data){
   return 0;
 }
 
-/** \internal
- * \brief add data at head of a buffer
- * \param buffer buffer
- * \param data data to add
- * \param len length of data
- * \return 0 on success, -1 on error.
+/**
+ * @internal
+ *
+ * @brief Add data at the head of a buffer.
+ *
+ * @param[in]  buffer   The buffer to add the data.
+ *
+ * @param[in]  data     The data to prepend.
+ *
+ * @param[in]  len      The length of data to prepend.
+ *
+ * @return              0 on success, -1 on error.
  */
 int buffer_prepend_data(struct ssh_buffer_struct *buffer, const void *data,
     uint32_t len) {
@@ -252,11 +305,17 @@ int buffer_prepend_data(struct ssh_buffer_struct *buffer, const void *data,
   return 0;
 }
 
-/** \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
- * \return 0 on success, -1 on error.
+/**
+ * @internal
+ *
+ * @brief Append data from a buffer to the tail of another buffer.
+ *
+ * @param[in]  buffer   The destination buffer.
+ *
+ * @param[in]  source   The source buffer to append. It doesn't take the
+ *                      position of the buffer into account.
+ *
+ * @return              0 on success, -1 on error.
  */
 int buffer_add_buffer(struct ssh_buffer_struct *buffer,
     struct ssh_buffer_struct *source) {
@@ -267,54 +326,80 @@ int buffer_add_buffer(struct ssh_buffer_struct *buffer,
   return 0;
 }
 
-/** \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()
+/**
+ * @brief Get a pointer on the head of a buffer.
+ *
+ * @param[in]  buffer   The buffer to get the head pointer.
+ *
+ * @return              A data pointer on the head. It doesn't take the position
+ *                      into account.
+ *
+ * @warning Don't expect data to be nul-terminated.
+ *
+ * @see buffer_get_rest()
+ * @see buffer_get_len()
  */
 void *buffer_get(struct ssh_buffer_struct *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()
+/**
+ * @internal
+ *
+ * @brief Get a pointer to the head of a buffer at the current position.
+ *
+ * @param[in]  buffer   The buffer to get the head pointer.
+ *
+ * @return              A pointer to the data from current position.
+ *
+ * @see buffer_get_rest_len()
+ * @see buffer_get()
  */
 void *buffer_get_rest(struct ssh_buffer_struct *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()
+/**
+ * @brief Get the length of the buffer, not counting position.
+ *
+ * @param[in]  buffer   The buffer to get the length from.
+ *
+ * @return              The length of the buffer.
+ *
+ * @see buffer_get()
  */
 uint32_t buffer_get_len(struct ssh_buffer_struct *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()
+/**
+ * @internal
+ *
+ * @brief Get the length of the buffer from the current position.
+ *
+ * @param[in]  buffer   The buffer to get the length from.
+ *
+ * @return              The length of the buffer.
+ *
+ * @see buffer_get_rest()
  */
 uint32_t buffer_get_rest_len(struct ssh_buffer_struct *buffer){
   buffer_verify(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
+/**
+ * @internal
+ *
+ * @brief Advance the position in the buffer.
+ *
+ * This has effect to "eat" bytes at head of the buffer.
+ *
+ * @param[in]  buffer   The buffer to advance the position.
+ *
+ * @param[in]  len      The number of bytes to eat.
+ *
+ * @return              The new size of the buffer.
  */
 uint32_t buffer_pass_bytes(struct ssh_buffer_struct *buffer, uint32_t len){
     buffer_verify(buffer);
@@ -330,11 +415,16 @@ uint32_t buffer_pass_bytes(struct ssh_buffer_struct *buffer, uint32_t 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
+/**
+ * @internal
+ *
+ * @brief Cut the end of the buffer.
+ *
+ * @param[in]  buffer   The buffer to cut.
+ *
+ * @param[in]  len      The number of bytes to remove from the tail.
+ *
+ * @return              The new size of the buffer.
  */
 uint32_t buffer_pass_bytes_end(struct ssh_buffer_struct *buffer, uint32_t len){
   buffer_verify(buffer);
@@ -345,13 +435,18 @@ uint32_t buffer_pass_bytes_end(struct ssh_buffer_struct *buffer, uint32_t 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.
+/**
+ * @internal
+ *
+ * @brief Get the remaining data out of the buffer and adjust the read pointer.
+ *
+ * @param[in]  buffer   The buffer to read.
+ *
+ * @param[in]  data     The data buffer where to store the data.
+ *
+ * @param[in]  len      The length to read from the buffer.
+ *
+ * @returns             0 if there is not enough data in buffer, len otherwise.
  */
 uint32_t buffer_get_data(struct ssh_buffer_struct *buffer, void *data, uint32_t len){
     /*
@@ -365,12 +460,18 @@ uint32_t buffer_get_data(struct ssh_buffer_struct *buffer, void *data, uint32_t
     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 uint8_t where to store the data
- * \returns 0 if there is not enough data in buffer
- * \returns 1 otherwise.
+
+/**
+ * @internal
+ *
+ * @brief Get a 8 bits unsigned int out of the buffer and adjusts the read
+ * pointer.
+ *
+ * @param[in]  buffer   The buffer to read.
+ *
+ * @param[in]   data    A pointer to a uint8_t where to store the data.
+ *
+ * @returns             0 if there is not enough data in buffer, 1 otherwise.
  */
 int buffer_get_u8(struct ssh_buffer_struct *buffer, uint8_t *data){
     return buffer_get_data(buffer,data,sizeof(uint8_t));
@@ -386,21 +487,30 @@ int buffer_get_u8(struct ssh_buffer_struct *buffer, uint8_t *data){
 int buffer_get_u32(struct ssh_buffer_struct *buffer, uint32_t *data){
     return buffer_get_data(buffer,data,sizeof(uint32_t));
 }
-/** \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 uint64_t where to store the data
- * \returns 0 if there is not enough data in buffer
- * \returns 8 otherwise.
+/**
+ * @internal
+ *
+ * @brief Get a 64 bits unsigned int out of the buffer and adjusts the read
+ * pointer.
+ *
+ * @param[in]  buffer   The buffer to read.
+ *
+ * @param[in]  data     A pointer to a uint64_t where to store the data.
+ *
+ * @returns             0 if there is not enough data in buffer, 8 otherwise.
  */
 int buffer_get_u64(struct ssh_buffer_struct *buffer, uint64_t *data){
     return buffer_get_data(buffer,data,sizeof(uint64_t));
 }
-/** \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.
+
+/**
+ * @internal
+ *
+ * @brief Get a SSH String out of the buffer and adjusts the read pointer.
+ *
+ * @param[in]  buffer   The buffer to read.
+ *
+ * @returns             The SSH String, NULL on error.
  */
 struct ssh_string_struct *buffer_get_ssh_string(struct ssh_buffer_struct *buffer) {
   uint32_t stringlen;
@@ -427,14 +537,18 @@ struct ssh_string_struct *buffer_get_ssh_string(struct ssh_buffer_struct *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
- */
 
+/**
+ * @internal
+ *
+ * @brief Get a mpint out of the buffer and adjusts the read pointer.
+ *
+ * @note This function is SSH-1 only.
+ *
+ * @param[in]  buffer   The buffer to read.
+ *
+ * @returns             The SSH String containing the mpint, NULL on error.
+ */
 struct ssh_string_struct *buffer_get_mpint(struct ssh_buffer_struct *buffer) {
   uint16_t bits;
   uint32_t len;
@@ -458,5 +572,7 @@ struct ssh_string_struct *buffer_get_mpint(struct ssh_buffer_struct *buffer) {
   }
   return str;
 }
-/** @} */
-/* vim: set ts=2 sw=2 et cindent: */
+
+/* @} */
+
+/* vim: set ts=4 sw=4 et cindent: */