ROBODoc documented. Patch by Ville Räsänen.

diff --git a/CHANGES b/CHANGES
index ce6d0da97a0b740201c6657ce2be1a440aedc36b..4b4dec2197dd4946a04a04eb06bf03fec915823d 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -1,3 +1,9 @@
+Sat Oct 19 13:32:15 CEST 2002  Pekka Riikonen <priikone@silcnet.org>
+
+       * ROBODoc documented lib/silcutil/silcbuffer.h and
+         lib/silcutil/silcdlist.h.  Patch by Ville Räsänen
+         <ville.rasanen@iki.fi>.
+

 Fri Oct 18 10:51:04 EEST 2002  Pekka Riikonen <priikone@silcnet.org>
 
        * Added support for auto-passphrase authentication from the
 Fri Oct 18 10:51:04 EEST 2002  Pekka Riikonen <priikone@silcnet.org>
 
        * Added support for auto-passphrase authentication from the

diff --git a/TODO b/TODO
index 3adaf9619113d224956cc80968a81238f339ec23..b9dac74501c8e31ca776184cd2943d0cd181cb85 100644 (file)
--- a/TODO
+++ b/TODO
@@ -54,10 +54,6 @@ TODO in Toolkit Documentation
 Stuff that needs to be done in order to complete the Tooolkit Reference
 Manual (Do these to 0.9.x).
 
 Stuff that needs to be done in order to complete the Tooolkit Reference
 Manual (Do these to 0.9.x).
 

- o ROBOdoc documenting missing from lib/silcutil/silcbuffer.h.
-
- o ROBOdoc documenting missing from lib/silcutil/silcdlist.h.
-

  o ROBOdoc documenting missing from lib/silccrypt/silccipher.h.
 
  o ROBOdoc documenting missing from lib/silccrypt/silcpkcs.h.
  o ROBOdoc documenting missing from lib/silccrypt/silccipher.h.
 
  o ROBOdoc documenting missing from lib/silccrypt/silcpkcs.h.

diff --git a/lib/silcutil/silcbuffer.h b/lib/silcutil/silcbuffer.h
index e0214337d7b8322b937d921d89d8ed358f5df2e4..6aa197fda40df74534ab77b76235adef9420b709 100644 (file)
--- a/lib/silcutil/silcbuffer.h
+++ b/lib/silcutil/silcbuffer.h
@@ -22,94 +22,109 @@
 #ifndef SILCBUFFER_H
 #define SILCBUFFER_H
 
 #ifndef SILCBUFFER_H
 #define SILCBUFFER_H
 

-/* 
-   SILC Buffer object.
-
-   SilcBuffer is very simple and easy to use, yet you can do to the
-   buffer almost anything you want with its method functions. The buffer
-   is constructed of four different data sections that in whole creates
-   the allocated data area. Following short description of the fields
-   of the buffer.
-
-   SilcUInt32 truelen;
-
-       True length of the buffer. This is set at the allocation of the
-       buffer and it should not be touched after that. This field should
-       be considered read-only.
-
-   SilcUInt32 len;
-
-       Length of the currently valid data area. Tells the length of the 
-       data at the buffer. This is set to zero at the allocation of the
-       buffer and should not be updated by hand. Method functions of the
-       buffer automatically updates this field. However, it is not
-       read-only field and can be updated manually if necessary.
-
-   unsiged char *head;
-
-       Head of the allocated buffer. This is the start of the allocated
-       data area and remains as same throughout the lifetime of the buffer.
-       However, the end of the head area or the start of the currently valid
-       data area is variable.
-
-       --------------------------------
-       | head  | data         | tail  |
-       --------------------------------
-       ^       ^
-
-       Current head section in the buffer is sb->data - sb->head.
-
-   unsigned char *data;
-
-       Currently valid data area. This is the start of the currently valid
-       main data area. The data area is variable in all directions.
-
-       --------------------------------
-       | head  | data         | tail  |
-       --------------------------------
-               ^              ^
- 
-       Current valid data area in the buffer is sb->tail - sb->data.
-
-    unsigned char *tail;
-
-       Tail of the buffer. This is the end of the currently valid data area
-       or start of the tail area. The start of the tail area is variable.
-
-       --------------------------------
-       | head  | data         | tail  |
-       --------------------------------
-                              ^       ^
-
-       Current tail section in the buffer is sb->end - sb->tail.
-
-   unsigned char *end;
-
-       End of the allocated buffer. This is the end of the allocated data
-       area and remains as same throughout the lifetime of the buffer.
-       Usually this field is not needed except when checking the size
-       of the buffer.
-
-       --------------------------------
-       | head  | data         | tail  |
-       --------------------------------
-                                      ^
-
-       Length of the entire buffer is (ie. truelen) sb->end - sb->head.
-
-    Currently valid data area is considered to be the main data area in
-    the buffer. However, the entire buffer is of course valid data and can
-    be used as such. Usually head section of the buffer includes different
-    kind of headers or similar. Data section includes the main data of
-    the buffer. Tail section can be seen as a reserve space of the data
-    section. Tail section can be pulled towards end thus the data section
-    becomes larger.
-
-    This buffer scheme is based on Linux kernel's Socket Buffer, the 
-    idea were taken directly from there and credits should go there.
-
-*/
-
+/****h* silcutil/SILC Buffer Interface
+ *
+ * DESCRIPTION
+ *
+ *    SilcBuffer is very simple and easy to use, yet you can do to the
+ *    buffer almost anything you want with its method functions. The buffer
+ *    is constructed of four different data sections that in whole creates
+ *    the allocated data area.
+ *
+ *    This buffer scheme is based on Linux kernel's Socket Buffer, the
+ *    idea were taken directly from there and credits should go there.
+ *
+ ***/
+
+/****s* silcutil/SilcBufferAPI/SilcBuffer
+ *
+ * NAME
+ *
+ *    typedef struct { ... } *SilcBuffer, SilcBufferStruct;
+ *
+ * DESCRIPTION
+ *
+ *    SILC Buffer object. Following short description of the fields
+ *    of the buffer.
+ *
+ * EXAMPLE
+ *
+ *    SilcUInt32 truelen;
+ *
+ *        True length of the buffer. This is set at the allocation of the
+ *        buffer and it should not be touched after that. This field should
+ *        be considered read-only.
+ *
+ *    SilcUInt32 len;
+ *
+ *        Length of the currently valid data area. Tells the length of the
+ *        data at the buffer. This is set to zero at the allocation of the
+ *        buffer and should not be updated by hand. Method functions of the
+ *        buffer automatically updates this field. However, it is not
+ *        read-only field and can be updated manually if necessary.
+ *
+ *    unsiged char *head;
+ *
+ *        Head of the allocated buffer. This is the start of the allocated
+ *        data area and remains as same throughout the lifetime of the buffer.
+ *        However, the end of the head area or the start of the currently valid
+ *        data area is variable.
+ *
+ *        --------------------------------
+ *        | head  | data         | tail  |
+ *        --------------------------------
+ *        ^       ^
+ *
+ *        Current head section in the buffer is sb->data - sb->head.
+ *
+ *    unsigned char *data;
+ *
+ *        Currently valid data area. This is the start of the currently valid
+ *        main data area. The data area is variable in all directions.
+ *
+ *        --------------------------------
+ *        | head  | data         | tail  |
+ *        --------------------------------
+ *                ^              ^
+ *
+ *        Current valid data area in the buffer is sb->tail - sb->data.
+ *
+ *     unsigned char *tail;
+ *
+ *        Tail of the buffer. This is the end of the currently valid data area
+ *        or start of the tail area. The start of the tail area is variable.
+ *
+ *        --------------------------------
+ *        | head  | data         | tail  |
+ *        --------------------------------
+ *                               ^       ^
+ *
+ *        Current tail section in the buffer is sb->end - sb->tail.
+ *
+ *    unsigned char *end;
+ *
+ *        End of the allocated buffer. This is the end of the allocated data
+ *        area and remains as same throughout the lifetime of the buffer.
+ *        Usually this field is not needed except when checking the size
+ *        of the buffer.
+ *
+ *        --------------------------------
+ *        | head  | data         | tail  |
+ *        --------------------------------
+ *                                       ^
+ *
+ *        Length of the entire buffer is (ie. truelen) sb->end - sb->head.
+ *
+ *     Currently valid data area is considered to be the main data area in
+ *     the buffer. However, the entire buffer is of course valid data and can
+ *     be used as such. Usually head section of the buffer includes different
+ *     kind of headers or similar. Data section includes the main data of
+ *     the buffer. Tail section can be seen as a reserve space of the data
+ *     section. Tail section can be pulled towards end, and thus the data
+ *     section becomes larger.
+ *
+ * SOURCE
+ */

 typedef struct {
   SilcUInt32 truelen;
   SilcUInt32 len;
 typedef struct {
   SilcUInt32 truelen;
   SilcUInt32 len;


@@ -118,15 +133,41 @@ typedef struct {
   unsigned char *tail;
   unsigned char *end;
 } *SilcBuffer, SilcBufferStruct;
   unsigned char *tail;
   unsigned char *end;
 } *SilcBuffer, SilcBufferStruct;

+/***/

 
 /* Macros */
 
 
 /* Macros */
 

-/* Returns the true length of the buffer. This is used to pull
-   the buffer area to the end of the buffer. */
+/****d* silcutil/SilcBufferAPI/SILC_BUFFER_END
+ * 
+ * NAME
+ *
+ *    #define SILC_BUFFER_END(...)
+ *
+ * DESCRIPTION
+ *
+ *    Returns the true length of the buffer. This is used to pull
+ *    the buffer area to the end of the buffer.
+ *
+ * SOURCE
+ */

 #define SILC_BUFFER_END(x) ((x)->end - (x)->head)
 #define SILC_BUFFER_END(x) ((x)->end - (x)->head)

+/***/

 
 /* Inline functions */
 
 
 /* Inline functions */
 

+/****f* silcutil/SilcBufferAPI/silc_buffer_alloc
+ *
+ * SYNOPSIS
+ *
+ *    static inline
+ *    SilcBuffer silc_buffer_alloc(SilcUInt32 len);
+ *
+ * DESCRIPTION
+ *
+ *    Allocates new SilcBuffer and returns it.
+ *
+ ***/
+ 

 static inline
 SilcBuffer silc_buffer_alloc(SilcUInt32 len)
 {
 static inline
 SilcBuffer silc_buffer_alloc(SilcUInt32 len)
 {


@@ -151,7 +192,18 @@ SilcBuffer silc_buffer_alloc(SilcUInt32 len)
   return sb;
 }
 
   return sb;
 }
 

-/* Free's a SilcBuffer */
+/****f* silcutil/SilcBufferAPI/silc_buffer_free
+ *
+ * SYNOPSIS
+ *
+ *    static inline
+ *    void silc_buffer_free(SilcBuffer sb);
+ *
+ * DESCRIPTION
+ *
+ *    Frees SilcBuffer.
+ *
+ ***/

 
 static inline
 void silc_buffer_free(SilcBuffer sb)
 
 static inline
 void silc_buffer_free(SilcBuffer sb)


@@ -165,10 +217,23 @@ void silc_buffer_free(SilcBuffer sb)
   }
 }
 
   }
 }
 

-/* Sets the `data' and `data_len' to the buffer pointer sent as argument.
-   The data area is automatically set to the `data_len'. This function
-   can be used to set the data to static buffer without needing any
-   memory allocations. The `data' will not be copied to the buffer. */
+/****f* silcutil/SilcBufferAPI/silc_buffer_set
+ *
+ * SYNOPSIS
+ *
+ *    static inline
+ *    void silc_buffer_set(SilcBuffer sb,
+ *                        unsigned char *data,
+ *                         SilcUInt32 data_len);
+ *
+ * DESCRIPTION
+ *
+ *    Sets the `data' and `data_len' to the buffer pointer sent as argument.
+ *    The data area is automatically set to the `data_len'. This function
+ *    can be used to set the data to static buffer without needing any
+ *    memory allocations. The `data' will not be copied to the buffer.
+ *
+ ***/

 
 static inline
 void silc_buffer_set(SilcBuffer sb, unsigned char *data, SilcUInt32 data_len)
 
 static inline
 void silc_buffer_set(SilcBuffer sb, unsigned char *data, SilcUInt32 data_len)


@@ -178,24 +243,34 @@ void silc_buffer_set(SilcBuffer sb, unsigned char *data, SilcUInt32 data_len)
   sb->len = sb->truelen = data_len;
 }
 
   sb->len = sb->truelen = data_len;
 }
 

-/* Pulls current data area towards end. The length of the currently
-   valid data area is also decremented. Returns pointer to the data
-   area before pulling. 
-
-   Example:
-   ---------------------------------
-   | head  | data       | tail     |
-   ---------------------------------
-           ^
-           Pulls the start of the data area.
-
-   ---------------------------------
-   | head     | data    | tail     |
-   ---------------------------------
-           ^
-*/
+/****f* silcutil/SilcBufferAPI/silc_buffer_pull
+ *
+ * SYNOPSIS
+ *
+ *    static inline
+ *    unsigned char *silc_buffer_pull(SilcBuffer sb, SilcUInt32 len);
+ *
+ * DESCRIPTION
+ *
+ *    Pulls current data area towards end. The length of the currently
+ *    valid data area is also decremented. Returns pointer to the data
+ *    area before pulling.
+ *
+ * EXAMPLE
+ *
+ *    ---------------------------------
+ *    | head  | data       | tail     |
+ *    ---------------------------------
+ *            ^
+ *            Pulls the start of the data area.
+ *
+ *    ---------------------------------
+ *    | head     | data    | tail     |
+ *    ---------------------------------
+ *            ^
+ ***/

 
 

-static inline 
+static inline

 unsigned char *silc_buffer_pull(SilcBuffer sb, SilcUInt32 len)
 {
   unsigned char *old_data = sb->data;
 unsigned char *silc_buffer_pull(SilcBuffer sb, SilcUInt32 len)
 {
   unsigned char *old_data = sb->data;


@@ -210,24 +285,35 @@ unsigned char *silc_buffer_pull(SilcBuffer sb, SilcUInt32 len)
   return old_data;
 }
 
   return old_data;
 }
 

-/* Pushes current data area towards beginning. Length of the currently
-   valid data area is also incremented. Returns a pointer to the 
-   data area before pushing. 
-
-   Example:
-   ---------------------------------
-   | head     | data    | tail     |
-   ---------------------------------
-              ^
-              Pushes the start of the data area.
-
-   ---------------------------------
-   | head  | data       | tail     |
-   ---------------------------------
-              ^
-*/
+/****f* silcutil/SilcBufferAPI/silc_buffer_push
+ *
+ * SYNOPSIS
+ *
+ *    static inline
+ *    unsigned char *silc_buffer_push(SilcBuffer sb, SilcUInt32 len);
+ *
+ * DESCRIPTION
+ *
+ *    Pushes current data area towards beginning. Length of the currently
+ *    valid data area is also incremented. Returns a pointer to the 
+ *    data area before pushing. 
+ *
+ * EXAMPLE
+ *
+ *    ---------------------------------
+ *    | head     | data    | tail     |
+ *    ---------------------------------
+ *               ^
+ *               Pushes the start of the data area.
+ *
+ *    ---------------------------------
+ *    | head  | data       | tail     |
+ *    ---------------------------------
+ *               ^
+ *
+ ***/

 
 

-static inline 
+static inline

 unsigned char *silc_buffer_push(SilcBuffer sb, SilcUInt32 len)
 {
   unsigned char *old_data = sb->data;
 unsigned char *silc_buffer_push(SilcBuffer sb, SilcUInt32 len)
 {
   unsigned char *old_data = sb->data;


@@ -242,24 +328,35 @@ unsigned char *silc_buffer_push(SilcBuffer sb, SilcUInt32 len)
   return old_data;
 }
 
   return old_data;
 }
 

-/* Pulls current tail section towards end. Length of the current valid
-   data area is also incremented. Returns a pointer to the data area 
-   before pulling.
-
-   Example:
-   ---------------------------------
-   | head  | data       | tail     |
-   ---------------------------------
-                        ^
-                        Pulls the start of the tail section.
-
-   ---------------------------------
-   | head  | data           | tail |
-   ---------------------------------
-                        ^
-*/
+/****f* silcutil/SilcBufferAPI/silc_buffer_pull_tail
+ *
+ * SYNOPSIS
+ *
+ *    static inline 
+ *    unsigned char *silc_buffer_pull_tail(SilcBuffer sb, SilcUInt32 len);
+ *
+ * DESCRIPTION
+ *
+ *    Pulls current tail section towards end. Length of the current valid
+ *    data area is also incremented. Returns a pointer to the data area 
+ *    before pulling.
+ *
+ * EXAMPLE
+ *
+ *    ---------------------------------
+ *    | head  | data       | tail     |
+ *    ---------------------------------
+ *                         ^
+ *                         Pulls the start of the tail section.
+ *
+ *    ---------------------------------
+ *    | head  | data           | tail |
+ *    ---------------------------------
+ *                         ^
+ *
+ ***/

 
 

-static inline 
+static inline

 unsigned char *silc_buffer_pull_tail(SilcBuffer sb, SilcUInt32 len)
 {
   unsigned char *old_tail = sb->tail;
 unsigned char *silc_buffer_pull_tail(SilcBuffer sb, SilcUInt32 len)
 {
   unsigned char *old_tail = sb->tail;


@@ -274,22 +371,33 @@ unsigned char *silc_buffer_pull_tail(SilcBuffer sb, SilcUInt32 len)
   return old_tail;
 }
 
   return old_tail;
 }
 

-/* Pushes current tail section towards beginning. Length of the current
-   valid data area is also decremented. Returns a pointer to the 
-   tail section before pushing. 
-
-   Example:
-   ---------------------------------
-   | head  | data           | tail |
-   ---------------------------------
-                            ^
-                            Pushes the start of the tail section.
-
-   ---------------------------------
-   | head  | data       | tail     |
-   ---------------------------------
-                            ^
-*/
+/****f* silcutil/SilcBufferAPI/silc_buffer_push_tail
+ *
+ * SYNOPSIS
+ *
+ *    static inline
+ *    unsigned char *silc_buffer_push_tail(SilcBuffer sb, SilcUInt32 len);
+ *
+ * DESCRIPTION
+ *
+ *    Pushes current tail section towards beginning. Length of the current
+ *    valid data area is also decremented. Returns a pointer to the
+ *    tail section before pushing.
+ *
+ * EXAMPLE
+ *
+ *    ---------------------------------
+ *    | head  | data           | tail |
+ *    ---------------------------------
+ *                             ^
+ *                             Pushes the start of the tail section.
+ *
+ *    ---------------------------------
+ *    | head  | data       | tail     |
+ *    ---------------------------------
+ *                             ^
+ *
+ ***/

 
 static inline
 unsigned char *silc_buffer_push_tail(SilcBuffer sb, SilcUInt32 len)
 
 static inline
 unsigned char *silc_buffer_push_tail(SilcBuffer sb, SilcUInt32 len)


@@ -306,19 +414,32 @@ unsigned char *silc_buffer_push_tail(SilcBuffer sb, SilcUInt32 len)
   return old_tail;
 }
 
   return old_tail;
 }
 

-/* Puts data at the head of the buffer. Returns pointer to the copied
-   data area. 
-   
-   Example:
-   ---------------------------------
-   | head  | data       | tail     |
-   ---------------------------------
-   ^
-   Puts data to the head section. 
-*/
+/****f* silcutil/SilcBufferAPI/silc_buffer_put_head
+ *
+ * SYNOPSIS
+ *
+ *    static inline
+ *    unsigned char *silc_buffer_put_head(SilcBuffer sb, 
+ *                                       const unsigned char *data,
+ *                                       SilcUInt32 len);
+ *
+ * DESCRIPTION
+ *
+ *    Puts data at the head of the buffer. Returns pointer to the copied
+ *    data area. 
+ *
+ * EXAMPLE
+ *
+ *    ---------------------------------
+ *    | head  | data       | tail     |
+ *    ---------------------------------
+ *    ^
+ *    Puts data to the head section. 
+ *
+ ***/

 
 static inline
 
 static inline

-unsigned char *silc_buffer_put_head(SilcBuffer sb, 
+unsigned char *silc_buffer_put_head(SilcBuffer sb,

                                    const unsigned char *data,
                                    SilcUInt32 len)
 {
                                    const unsigned char *data,
                                    SilcUInt32 len)
 {


@@ -328,19 +449,32 @@ unsigned char *silc_buffer_put_head(SilcBuffer sb,
   return (unsigned char *)memcpy(sb->head, data, len);
 }
 
   return (unsigned char *)memcpy(sb->head, data, len);
 }
 

-/* Puts data at the start of the valid data area. Returns a pointer 
-   to the copied data area. 
-
-   Example:
-   ---------------------------------
-   | head  | data       | tail     |
-   ---------------------------------
-           ^
-           Puts data to the data section.
-*/
+/****f* silcutil/SilcBufferAPI/silc_buffer_put
+ *
+ * SYNOPSIS
+ *
+ *    static inline
+ *    unsigned char *silc_buffer_put(SilcBuffer sb,
+ *                                  const unsigned char *data,
+ *                                  SilcUInt32 len);
+ *
+ * DESCRIPTION
+ *
+ *    Puts data at the start of the valid data area. Returns a pointer
+ *    to the copied data area.
+ *
+ * EXAMPLE
+ *
+ *    ---------------------------------
+ *    | head  | data       | tail     |
+ *    ---------------------------------
+ *            ^
+ *            Puts data to the data section.
+ *
+ ***/

 
 static inline
 
 static inline

-unsigned char *silc_buffer_put(SilcBuffer sb, 
+unsigned char *silc_buffer_put(SilcBuffer sb,

                               const unsigned char *data,
                               SilcUInt32 len)
 {
                               const unsigned char *data,
                               SilcUInt32 len)
 {


@@ -350,19 +484,32 @@ unsigned char *silc_buffer_put(SilcBuffer sb,
   return (unsigned char *)memcpy(sb->data, data, len);
 }
 
   return (unsigned char *)memcpy(sb->data, data, len);
 }
 

-/* Puts data at the tail of the buffer. Returns pointer to the copied
-   data area. 
-
-   Example:
-   ---------------------------------
-   | head  | data           | tail |
-   ---------------------------------
-                            ^
-                           Puts data to the tail section.
-*/
+/****f* silcutil/SilcBufferAPI/silc_buffer_put_tail
+ *
+ * SYNOPSIS
+ *
+ *    static inline
+ *    unsigned char *silc_buffer_put_tail(SilcBuffer sb,
+ *                                       const unsigned char *data,
+ *                                       SilcUInt32 len);
+ *
+ * DESCRIPTION
+ *
+ *    Puts data at the tail of the buffer. Returns pointer to the copied
+ *    data area. 
+ *
+ * EXAMPLE
+ *
+ *    ---------------------------------
+ *    | head  | data           | tail |
+ *    ---------------------------------
+ *                             ^
+ *                            Puts data to the tail section.
+ *
+ ***/

 
 static inline
 
 static inline

-unsigned char *silc_buffer_put_tail(SilcBuffer sb, 
+unsigned char *silc_buffer_put_tail(SilcBuffer sb,

                                    const unsigned char *data,
                                    SilcUInt32 len)
 {
                                    const unsigned char *data,
                                    SilcUInt32 len)
 {


@@ -372,9 +519,20 @@ unsigned char *silc_buffer_put_tail(SilcBuffer sb,
   return (unsigned char *)memcpy(sb->tail, data, len);
 }
 
   return (unsigned char *)memcpy(sb->tail, data, len);
 }
 

-/* Allocates `len' bytes size buffer and moves the tail area automaticlly
-   `len' bytes so that the buffer is ready to use without calling the
-   silc_buffer_pull_tail. */
+/****f* silcutil/SilcBufferAPI/silc_buffer_alloc_size
+ *
+ * SYNOPSIS
+ *
+ *    static inline
+ *    SilcBuffer silc_buffer_alloc_size(SilcUInt32 len);
+ *
+ * DESCRIPTION
+ *
+ *    Allocates `len' bytes size buffer and moves the tail area automatically
+ *    `len' bytes so that the buffer is ready to use without calling the
+ *    silc_buffer_pull_tail.
+ *
+ ***/

 
 static inline
 SilcBuffer silc_buffer_alloc_size(SilcUInt32 len)
 
 static inline
 SilcBuffer silc_buffer_alloc_size(SilcUInt32 len)


@@ -386,8 +544,19 @@ SilcBuffer silc_buffer_alloc_size(SilcUInt32 len)
   return sb;
 }
 
   return sb;
 }
 

-/* Clears and initialiazes the buffer to the state as if it was just
-   allocated by silc_buffer_alloc. */
+/****f* silcutil/SilcBufferAPI/silc_buffer_clear
+ *
+ * SYNOPSIS
+ *
+ *    static inline
+ *    void silc_buffer_clear(SilcBuffer sb);
+ *
+ * DESCRIPTION
+ *
+ *    Clears and initialiazes the buffer to the state as if it was just
+ *    allocated by silc_buffer_alloc.
+ *
+ ***/

 
 static inline
 void silc_buffer_clear(SilcBuffer sb)
 
 static inline
 void silc_buffer_clear(SilcBuffer sb)


@@ -398,9 +567,20 @@ void silc_buffer_clear(SilcBuffer sb)
   sb->len = 0;
 }
 
   sb->len = 0;
 }
 

-/* Generates copy of a SilcBuffer. This copies everything inside the
-   currently valid data area, nothing more. Use silc_buffer_clone to
-   copy entire buffer. */
+/****f* silcutil/SilcBufferAPI/silc_buffer_copy
+ *
+ * SYNOPSIS
+ *
+ *    static inline
+ *    SilcBuffer silc_buffer_copy(SilcBuffer sb);
+ *
+ * DESCRIPTION
+ *
+ *    Generates copy of a SilcBuffer. This copies everything inside the
+ *    currently valid data area, nothing more. Use silc_buffer_clone to
+ *    copy entire buffer.
+ *
+ ***/

 
 static inline
 SilcBuffer silc_buffer_copy(SilcBuffer sb)
 
 static inline
 SilcBuffer silc_buffer_copy(SilcBuffer sb)


@@ -415,9 +595,20 @@ SilcBuffer silc_buffer_copy(SilcBuffer sb)
   return sb_new;
 }
 
   return sb_new;
 }
 

-/* Clones SilcBuffer. This generates new SilcBuffer and copies
-   everything from the source buffer. The result is exact clone of
-   the original buffer. */
+/****f* silcutil/SilcBufferAPI/silc_buffer_clone
+ *
+ * SYNOPSIS
+ *
+ *    static inline
+ *    SilcBuffer silc_buffer_clone(SilcBuffer sb);
+ *
+ * DESCRIPTION
+ *
+ *    Clones SilcBuffer. This generates new SilcBuffer and copies
+ *    everything from the source buffer. The result is exact clone of
+ *    the original buffer.
+ *
+ ***/

 
 static inline
 SilcBuffer silc_buffer_clone(SilcBuffer sb)
 
 static inline
 SilcBuffer silc_buffer_clone(SilcBuffer sb)


@@ -435,9 +626,20 @@ SilcBuffer silc_buffer_clone(SilcBuffer sb)
   return sb_new;
 }
 
   return sb_new;
 }
 

-/* Reallocates buffer. Old data is saved into the new buffer. Returns
-   new SilcBuffer pointer. The buffer is exact clone of the old one
-   except that there is now more space at the end of buffer. */
+/****f* silcutil/SilcBufferAPI/silc_buffer_realloc
+ *
+ * SYNOPSIS
+ *
+ *    static inline
+ *    SilcBuffer silc_buffer_realloc(SilcBuffer sb, SilcUInt32 newsize);
+ *
+ * DESCRIPTION
+ *
+ *    Reallocates buffer. Old data is saved into the new buffer. Returns
+ *    new SilcBuffer pointer. The buffer is exact clone of the old one
+ *    except that there is now more space at the end of buffer.
+ *
+ ***/

 
 static inline
 SilcBuffer silc_buffer_realloc(SilcBuffer sb, SilcUInt32 newsize)
 
 static inline
 SilcBuffer silc_buffer_realloc(SilcBuffer sb, SilcUInt32 newsize)

diff --git a/lib/silcutil/silcdlist.h b/lib/silcutil/silcdlist.h
index 8ea683b8a41ac7c2e2f158b30099124b5add98e7..2457ab89529dd7dc1f10f9f6391f65a9c44647c5 100644 (file)
--- a/lib/silcutil/silcdlist.h
+++ b/lib/silcutil/silcdlist.h
@@ -22,37 +22,75 @@
 #define SILDCLIST_H
 
 #include "silclist.h"
 #define SILDCLIST_H
 
 #include "silclist.h"

+ 
+/****h* silcutil/SILC Dynamic List Interface
+ *
+ * DESCRIPTION
+ *
+ *    SILC Dynamic List API can be used to add opaque contexts to list that
+ *    will automatically allocate list entries.  Normal SILC List API cannot
+ *    be used for this purpose because in that case the context passed to the
+ *    list must be defined as list structure already.  This is not the case in
+ *    SilcDList.
+ *
+ *    This is slower than SilcList because this requires one extra memory
+ *    allocation when adding new entries to the list.  The context is probably
+ *    allocated already and the new list entry requires one additional memory
+ *    allocation.  The memory allocation and freeing is done automatically in
+ *    the API and does not show to the caller.
+ *
+ ***/

 
 

-/*
-   SILC Dynamic List API
-
-   SILC Dynamic List API can be used to add opaque contexts to list that will
-   automatically allocate list entries.  Normal SILC List API cannot be used
-   for this purpose because in that case the context passed to the list must
-   be defined as list structure already.  This is not the case in SilcDList.
-
-   This is slower than SilcList because this requires one extra memory 
-   allocation when adding new entries to the list.  The context is probably
-   allocated already and the new list entry requires one additional memory 
-   allocation.  The memory allocation and free'ing is done automatically in
-   the API and does not show to the caller.
-*/
-
-/* SilcDList object. This is the actual SilcDList object that is used by
-   application. Application defines this object and adds context's to this
-   list with functions defined below. */
+/****s* silcutil/SilcDListAPI/SilcDList
+ *
+ * NAME
+ *
+ *    typedef struct { ... } *SilcDList;
+ *
+ * DESCRIPTION
+ *
+ *    This is the actual SilcDList object that is used by application.
+ *    Application defines this object and adds contexts to this list with
+ *    Dynamic List Interface functions.
+ *
+ * SOURCE
+ */

 typedef struct {
   SilcList list;
 } *SilcDList;
 typedef struct {
   SilcList list;
 } *SilcDList;

+/***/

 
 

-/* SilcDListEntry structure, one entry in the list. This MUST NOT be used
-   directly by the application. */
+/****s* silcutil/SilcDListAPI/SilcDListEntry
+ *
+ * NAME
+ *
+ *    typedef struct SilcDListEntryStruct { ... } *SilcDListEntry;
+ *
+ * DESCRIPTION
+ *
+ *    SilcDListEntry structure, one entry in the list. This MUST NOT be used
+ *    directly by the application.
+ *
+ * SOURCE
+ */

 typedef struct SilcDListEntryStruct {
   void *context;
   struct SilcDListEntryStruct *next;
 } *SilcDListEntry;
 typedef struct SilcDListEntryStruct {
   void *context;
   struct SilcDListEntryStruct *next;
 } *SilcDListEntry;

+/***/

 
 

-/* Initializes SilcDList. */
+/****f* silcutil/SilcDListAPI/silc_dlist_init
+ *
+ * SYNOPSIS
+ * 
+ *    static inline
+ *    SilcDList silc_dlist_init();
+ *
+ * DESCRIPTION
+ *
+ *    Initializes SilcDList.
+ *
+ ***/

 
 static inline
 SilcDList silc_dlist_init()
 
 static inline
 SilcDList silc_dlist_init()


@@ -65,8 +103,19 @@ SilcDList silc_dlist_init()
   return list;
 }
 
   return list;
 }
 

-/* Uninits and free's all memory. Must be called to free memory. Does NOT
-   free the contexts saved by caller. */
+/****f* silcutil/SilcDListAPI/silc_dlist_uninit
+ *
+ * SYNOPSIS
+ *
+ *    static inline
+ *    void silc_dlist_uninit(SilcDList list);
+ *
+ * DESCRIPTION
+ *
+ *    Uninits and frees all memory. Must be called to free memory. Does NOT
+ *    free the contexts saved by caller.
+ *
+ ***/

 
 static inline
 void silc_dlist_uninit(SilcDList list)
 
 static inline
 void silc_dlist_uninit(SilcDList list)


@@ -82,7 +131,18 @@ void silc_dlist_uninit(SilcDList list)
   }
 }
 
   }
 }
 

-/* Return the number of entries in the list */
+/****f* silcutil/SilcDListAPI/silc_dlist_count
+ *
+ * SYNOPSIS
+ *
+ *    static inline
+ *    int silc_dlist_count(SilcDList list);
+ *
+ * DESCRIPTION
+ *
+ * Return the number of entries in the list.
+ *
+ ***/

 
 static inline
 int silc_dlist_count(SilcDList list)
 
 static inline
 int silc_dlist_count(SilcDList list)


@@ -90,8 +150,19 @@ int silc_dlist_count(SilcDList list)
   return silc_list_count(list->list);
 }
 
   return silc_list_count(list->list);
 }
 

-/* Set the start of the list. This prepares the list for traversing entries
-   from the start of the list. */
+/****f* silcutil/SilcDListAPI/silc_dlist_start
+ *
+ * SYNOPSIS
+ *
+ *    static inline
+ *    void silc_dlist_start(SilcDList list);
+ *
+ * DESCRIPTION
+ *
+ *    Set the start of the list. This prepares the list for traversing entries
+ *    from the start of the list.
+ *
+ ***/

 
 static inline
 void silc_dlist_start(SilcDList list)
 
 static inline
 void silc_dlist_start(SilcDList list)


@@ -99,8 +170,19 @@ void silc_dlist_start(SilcDList list)
   silc_list_start(list->list);
 }
 
   silc_list_start(list->list);
 }
 

-/* Adds new entry to the list. This is the default function to add new
-   entries to the list. */
+/****f* silcutil/SilcDListAPI/silc_dlist_add
+ *
+ * SYNOPSIS
+ *
+ *    static inline
+ *    void silc_dlist_add(SilcDList list, void *context);
+ *
+ * DESCRIPTION
+ *
+ *    Adds new entry to the list. This is the default function to add new
+ *    entries to the list.
+ *
+ ***/

 
 static inline
 void silc_dlist_add(SilcDList list, void *context)
 
 static inline
 void silc_dlist_add(SilcDList list, void *context)


@@ -110,7 +192,18 @@ void silc_dlist_add(SilcDList list, void *context)
   silc_list_add(list->list, e);
 }
 
   silc_list_add(list->list, e);
 }
 

-/* Remove entry from the list. Returns < 0 on error, 0 otherwise. */
+/****f* silcutil/SilcDListAPI/silc_dlist_del
+ *
+ * SYNOPSIS
+ *
+ *    static inline
+ *    void silc_dlist_del(SilcDList list, void *context);
+ *
+ * DESCRIPTION
+ *
+ *    Remove entry from the list. Returns < 0 on error, 0 otherwise.
+ *
+ ***/

 
 static inline
 void silc_dlist_del(SilcDList list, void *context)
 
 static inline
 void silc_dlist_del(SilcDList list, void *context)


@@ -127,19 +220,31 @@ void silc_dlist_del(SilcDList list, void *context)
   }
 }
 
   }
 }
 

-/* Returns current entry from the list and moves the list pointer forward
-   so that calling this next time returns the next entry from the list. This
-   can be used to traverse the list. Return SILC_LIST_END when the entire
-   list has ben traversed. Later, silc_list_start must be called again when 
-   re-starting list traversing. Example:
-
-   // Traverse the list from the beginning to the end 
-   silc_dlist_start(list)
-   while ((entry = silc_dlist_get(list)) != SILC_LIST_END) {
-     ...
-   }
-   
-*/
+/****f* silcutil/SilcDListAPI/silc_dlist_get
+ *
+ * SYNOPSIS
+ *
+ *    static inline
+ *    void *silc_dlist_get(SilcDList list);
+ *
+ * DESCRIPTION
+ *
+ *    Returns current entry from the list and moves the list pointer forward
+ *    so that calling this next time returns the next entry from the list.
+ *    This can be used to traverse the list. Return SILC_LIST_END when the
+ *    entire list has been traversed. Later, silc_list_start must be called
+ *    again when re-starting list traversing.
+ *
+ * EXAMPLE
+ *
+ *    // Traverse the list from the beginning to the end 
+ *    silc_dlist_start(list)
+ *    while ((entry = silc_dlist_get(list)) != SILC_LIST_END) {
+ *      ...
+ *    }
+ *
+ ***/
+

 static inline
 void *silc_dlist_get(SilcDList list)
 {
 static inline
 void *silc_dlist_get(SilcDList list)
 {