-/*
- 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.
-
- I left sorting functions out because I don't know whether we need them.
- If needed, just copy them from silclist.h
-
-*/
-
-/* 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. */
-typedef struct {
+/****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. The simpler SilcList 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. But SilcDList is a bit slower than SilcList because it
+ * requires memory allocation when adding new entries to the list.
+ *
+ * SILC Dynamic List is not thread-safe. If the same list context must be
+ * used in multithreaded environment concurrency control must be employed.
+ *
+ * EXAMPLE
+ *
+ * SilcDList list = silc_dlist_init();
+ *
+ * silc_dlist_add(list, entry1);
+ * silc_dlist_add(list, entry2);
+ *
+ * // Traverse the list from the beginning to the end
+ * silc_dlist_start(list)
+ * while ((entry = silc_dlist_get(list)) != SILC_LIST_END) {
+ * ...
+ * }
+ *
+ * silc_dlist_uninit(list);
+ *
+ ***/
+
+/****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.
+ *
+ ***/
+typedef struct SilcDListStruct {
+ SilcStack stack;