From 5c0580bfaa956973c2e292d98cb3df490c0a2fde Mon Sep 17 00:00:00 2001
From: Pekka Riikonen <priikone@silcnet.org>
Date: Tue, 17 Jul 2007 08:53:12 +0000
Subject: [PATCH] 	Added examples to headers.

---
 lib/silcutil/silcasync.h  | 26 ++++++++++++++++++++++++++
 lib/silcutil/silcatomic.h | 13 +++++++++++++
 lib/silcutil/silcbuffmt.h | 15 +++++++++++++++
 lib/silcutil/silccond.h   | 19 +++++++++++++++++++
 lib/silcutil/silcdlist.h  | 15 +++++++++++++++
 lib/silcutil/silcdll.h    | 13 +++++++++++++
 lib/silcutil/silctimer.h  | 11 +++++++++++
 7 files changed, 112 insertions(+)

diff --git a/lib/silcutil/silcasync.h b/lib/silcutil/silcasync.h
index 2853e9c3..0cc2190e 100644
--- a/lib/silcutil/silcasync.h
+++ b/lib/silcutil/silcasync.h
@@ -35,6 +35,32 @@
  * operation, no callback function will be called back to the upper layer.
  * This must be remembered when implementing the operation layer.
  *
+ * EXAMPLE
+ *
+ * SilcAsyncOperation async_call(Callback callback, void *cb_context)
+ * {
+ *   SilcAsyncOperation op;
+ *   OpContext ctx;
+ *
+ *   // Allocate async operation so that caller can control us, like abort
+ *   op = silc_async_alloc(async_call_abort, NULL, ctx);
+ *   ctx->callback = callback;
+ *
+ *   ...
+ *
+ *   // Return async operation for upper layer
+ *   return op;
+ * }
+ *
+ * // This callback is called when silc_async_abort is called by upper layer.
+ * // The callback given to async_call must not be called after this.
+ * void async_call_abort(SilcAsyncOperation op, void *context)
+ * {
+ *   OpContext ctx = context;
+ *   ctx->aborted = TRUE;
+ *   ctx->callback = NULL;
+ * }
+ *
  ***/
 
 #ifndef SILCASYNC_H
diff --git a/lib/silcutil/silcatomic.h b/lib/silcutil/silcatomic.h
index 3a49aecf..5f3ea2e1 100644
--- a/lib/silcutil/silcatomic.h
+++ b/lib/silcutil/silcatomic.h
@@ -35,6 +35,19 @@
  *
  * Fast operations are supported on: x86, x86_64, ia64, PPC
  *
+ * EXAMPLE
+ *
+ * SilcAtomic32 refcnt;
+ *
+ * // Initialize atomic variable
+ * silc_atomic_init32(&refcnt, 0);
+ *
+ * // Increment referene counter by one
+ * silc_atomic_add_int32(&refcnt, 1);
+ *
+ * // Uninitialize atomic variable
+ * silc_atomic_uninit32(&refcnt);
+ *
  ***/
 
 #ifndef SILCATOMIC_H
diff --git a/lib/silcutil/silcbuffmt.h b/lib/silcutil/silcbuffmt.h
index cd654de5..fc213001 100644
--- a/lib/silcutil/silcbuffmt.h
+++ b/lib/silcutil/silcbuffmt.h
@@ -30,6 +30,21 @@
  * in multithreaded environment with a same SilcBuffer context without
  * concurrency control.
  *
+ * EXAMPLE
+ *
+ * SilcBufferStruct buffer;
+ *
+ * memset(&buffer, 0, sizeof(buffer));
+ * ret = silc_buffer_format(&buffer,
+ *                          SILC_STR_UI_INT(intval),
+ *                          SILC_STR_CHAR(charval),
+ *                          SILC_STR_UI_INT(intval),
+ *                          SILC_STR_SHORT(str_len),
+ *                          SILC_STR_DATA(str, str_len),
+ *                          SILC_STR_END);
+ * if (ret < 0)
+ *   error;
+ *
  ***/
 
 #ifndef SILCBUFFMT_H
diff --git a/lib/silcutil/silccond.h b/lib/silcutil/silccond.h
index 1fe8bb21..08110d81 100644
--- a/lib/silcutil/silccond.h
+++ b/lib/silcutil/silccond.h
@@ -25,6 +25,25 @@
  * Condition variables enable threads to suspend execution and yield
  * the processors until some predicate on some shared data is satisfied.
  *
+ * EXAMPLE
+ *
+ * Thread 1:
+ *
+ * // Wait for signal
+ * silc_mutex_lock(lock);
+ * while (c->a == NULL)
+ *   silc_cond_wait(cond, lock);
+ * ...
+ * silc_mutex_unlock(lock);
+ *
+ * Thread 2:
+ *
+ * // Signal
+ * silc_mutex_lock(lock);
+ * c->a = context;
+ * silc_cond_signal(cond);
+ * silc_mutex_unlock(lock);
+ *
  ***/
 
 #ifndef SILCCOND_H
diff --git a/lib/silcutil/silcdlist.h b/lib/silcutil/silcdlist.h
index 238c008e..9c951e49 100644
--- a/lib/silcutil/silcdlist.h
+++ b/lib/silcutil/silcdlist.h
@@ -36,6 +36,21 @@
  * 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
diff --git a/lib/silcutil/silcdll.h b/lib/silcutil/silcdll.h
index 3da325b4..d0d2adf8 100644
--- a/lib/silcutil/silcdll.h
+++ b/lib/silcutil/silcdll.h
@@ -24,6 +24,19 @@
  * Platform independent iterface for loading and using shared objects and
  * dynamically linked libraries (DLLs).
  *
+ * EXAMPLE
+ *
+ * SilcDll dll;
+ * SilcFuncCb function;
+ *
+ * dll = silc_dll_load("/path/to/my.so");
+ * function = silc_dll_getsym(dll, "my_function");
+ *
+ * // Call the funtion
+ * function(arg1, arg2);
+ *
+ * silc_dll_close(dll);
+ *
  ***/
 
 #ifndef SILCDLL_H
diff --git a/lib/silcutil/silctimer.h b/lib/silcutil/silctimer.h
index 79c57750..c53da041 100644
--- a/lib/silcutil/silctimer.h
+++ b/lib/silcutil/silctimer.h
@@ -18,10 +18,21 @@
 */
 
 /****h* silcutil/SILC Timer Interface
+ *
+ * DESCRIPTION
  *
  * SILC Timer interface provides a simple way to measure time intervals.
  * The SILC Timer works with microsecond resolution, depending on platform.
  *
+ * EXAMPLE
+ *
+ * SilcTimerStruct timer;
+ *
+ * silc_timer_start(&timer);
+ * ... time passes ...
+ * silc_timer_stop(&timer);
+ * silc_timer_value(&timer, &elapsed_sec, &elapsed_usec);
+ *
  ***/
 
 #ifndef SILCTIMER_H
-- 
2.24.0