From 7f1987666fa9ffef6cfff0ceaf826c297a2d0de1 Mon Sep 17 00:00:00 2001
From: Mano Stienen <manostienen@gmail.com>
Date: Fri, 11 Jul 2008 05:02:47 +0200
Subject: [PATCH 1/5] moved documentation from rwlock.c to .h

---
 src/lib/rwlock.c | 33 ++++-----------------------------
 src/lib/rwlock.h | 33 +++++++++++++++++++++++++++++----
 2 files changed, 33 insertions(+), 33 deletions(-)

diff --git a/src/lib/rwlock.c b/src/lib/rwlock.c
index 077ff9766..71e3c9dc8 100644
--- a/src/lib/rwlock.c
+++ b/src/lib/rwlock.c
@@ -34,11 +34,6 @@ LUMIERA_ERROR_DEFINE(RWLOCK_WLOCK, "wlock");
  */
 
 
-/**
- * Initialize a rwlock
- * @param self is a pointer to the rwlock to be initialized
- * @return self as given
- */
 LumieraRWLock
 lumiera_rwlock_init (LumieraRWLock self)
 {
@@ -49,11 +44,7 @@ lumiera_rwlock_init (LumieraRWLock self)
   return self;
 }
 
-/**
- * destroy a rwlock
- * @param self is a pointer to the rwlock to be initialized
- * @return self on success or NULL at error
- */
+
 LumieraRWLock
 lumiera_rwlock_destroy (LumieraRWLock self)
 {
@@ -68,13 +59,7 @@ lumiera_rwlock_destroy (LumieraRWLock self)
 
 
 
-/**
- * initialize a rwlockacquirer state
- * @param self rwlockacquirer to be initialized, must be an automatic variable
- * @param rwlock associated rwlock
- * @param state initial state of the mutex, either LUMIERA_RDLOCKED, LUMIERA_WRLOCKED or LUMIERA_UNLOCKED
- * @return self as given or NULL on error
- */
+
 LumieraRWLockacquirer
 lumiera_rwlockacquirer_init (LumieraRWLockacquirer self, LumieraRWLock rwlock, enum lumiera_lockstate state)
 {
@@ -118,12 +103,7 @@ lumiera_rwlockacquirer_init (LumieraRWLockacquirer self, LumieraRWLock rwlock, e
 }
 
 
-/**
- * readlock the rwlock.
- * must not already be locked
- * @param self rwlockacquirer associated with a rwlock
- * @return self as given or NULL on error
- */
+
 LumieraRWLockacquirer
 lumiera_rwlockacquirer_rdlock (LumieraRWLockacquirer self)
 {
@@ -149,12 +129,7 @@ lumiera_rwlockacquirer_rdlock (LumieraRWLockacquirer self)
 }
 
 
-/**
- * writelock the rwlock.
- * must not already be locked
- * @param self rwlockacquirer associated with a rwlock
- * @return self as given or NULL on error
- */
+
 LumieraRWLockacquirer
 lumiera_rwlockacquirer_wrlock (LumieraRWLockacquirer self)
 {
diff --git a/src/lib/rwlock.h b/src/lib/rwlock.h
index d58627dda..c51f78076 100644
--- a/src/lib/rwlock.h
+++ b/src/lib/rwlock.h
@@ -55,11 +55,19 @@ struct lumiera_rwlock_struct
 typedef struct lumiera_rwlock_struct lumiera_rwlock;
 typedef lumiera_rwlock* LumieraRWLock;
 
-
+/**
+ * Initialize a rwlock
+ * @param self is a pointer to the rwlock to be initialized
+ * @return self as given
+ */
 LumieraRWLock
 lumiera_rwlock_init (LumieraRWLock self);
 
-
+/**
+ * destroy a rwlock
+ * @param self is a pointer to the rwlock to be initialized
+ * @return self on success or NULL at error
+ */
 LumieraRWLock
 lumiera_rwlock_destroy (LumieraRWLock self);
 
@@ -88,14 +96,31 @@ lumiera_rwlockacquirer_ensureunlocked (LumieraRWLockacquirer self)
 #define lumiera_rwlockacquirer \
 lumiera_rwlockacquirer NOBUG_CLEANUP(lumiera_rwlockacquirer_ensureunlocked)
 
-
+/**
+ * initialize a rwlockacquirer state
+ * @param self rwlockacquirer to be initialized, must be an automatic variable
+ * @param rwlock associated rwlock
+ * @param state initial state of the mutex, either LUMIERA_RDLOCKED, LUMIERA_WRLOCKED or LUMIERA_UNLOCKED
+ * @return self as given or NULL on error
+ */
 LumieraRWLockacquirer
 lumiera_rwlockacquirer_init (LumieraRWLockacquirer self, LumieraRWLock rwlock, enum lumiera_lockstate state);
 
+/**
+ * readlock the rwlock.
+ * must not already be locked
+ * @param self rwlockacquirer associated with a rwlock
+ * @return self as given or NULL on error
+ */
 LumieraRWLockacquirer
 lumiera_rwlockacquirer_rdlock (LumieraRWLockacquirer self);
 
-
+/**
+ * writelock the rwlock.
+ * must not already be locked
+ * @param self rwlockacquirer associated with a rwlock
+ * @return self as given or NULL on error
+ */
 LumieraRWLockacquirer
 lumiera_rwlockacquirer_wrlock (LumieraRWLockacquirer self);
 

From 1d8bc9842946d8d90c36f4beb3e34ee8a0d31cf1 Mon Sep 17 00:00:00 2001
From: Mano Stienen <manostienen@gmail.com>
Date: Fri, 11 Jul 2008 06:32:56 +0200
Subject: [PATCH 2/5] moved documentation from mutex.c to .h

---
 src/lib/mutex.c | 11 +----------
 src/lib/mutex.h | 10 ++++++++++
 2 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/src/lib/mutex.c b/src/lib/mutex.c
index b7c5f1844..20b0cce70 100644
--- a/src/lib/mutex.c
+++ b/src/lib/mutex.c
@@ -31,11 +31,6 @@ LUMIERA_ERROR_DEFINE (MUTEX_UNLOCK, "Mutex unlocking failed");
 LUMIERA_ERROR_DEFINE (MUTEX_DESTROY, "Mutex destroy failed");
 
 
-/**
- * Initialize a mutex variable
- * @param self is a pointer to the mutex to be initialized
- * @return self as given
- */
 LumieraMutex
 lumiera_mutex_init (LumieraMutex self)
 {
@@ -46,11 +41,7 @@ lumiera_mutex_init (LumieraMutex self)
   return self;
 }
 
-/**
- * Destroy a mutex variable
- * @param self is a pointer to the mutex to be destroyed
- * @return self as given
- */
+
 LumieraMutex
 lumiera_mutex_destroy (LumieraMutex self)
 {
diff --git a/src/lib/mutex.h b/src/lib/mutex.h
index f19058e7a..7e67b550a 100644
--- a/src/lib/mutex.h
+++ b/src/lib/mutex.h
@@ -51,10 +51,20 @@ typedef struct lumiera_mutex_struct lumiera_mutex;
 typedef lumiera_mutex* LumieraMutex;
 
 
+/**
+ * Initialize a mutex variable
+ * @param self is a pointer to the mutex to be initialized
+ * @return self as given
+ */
 LumieraMutex
 lumiera_mutex_init (LumieraMutex self);
 
 
+/**
+ * Destroy a mutex variable
+ * @param self is a pointer to the mutex to be destroyed
+ * @return self as given
+ */
 LumieraMutex
 lumiera_mutex_destroy (LumieraMutex self);
 

From 6838dbe12a5d5534b98afc54c10b1d70641dd064 Mon Sep 17 00:00:00 2001
From: Mano Stienen <manostienen@gmail.com>
Date: Fri, 11 Jul 2008 08:15:08 +0200
Subject: [PATCH 3/5] documentation from condition.c and reference.c moved to
 .h

---
 src/lib/condition.c  | 11 +----------
 src/lib/condition.h  | 10 ++++++++++
 src/lib/references.c | 44 ++++----------------------------------------
 src/lib/references.h | 40 ++++++++++++++++++++++++++++++++++++++++
 4 files changed, 55 insertions(+), 50 deletions(-)

diff --git a/src/lib/condition.c b/src/lib/condition.c
index 60e8b6f10..ad4ae6b76 100644
--- a/src/lib/condition.c
+++ b/src/lib/condition.c
@@ -28,11 +28,7 @@
 
 LUMIERA_ERROR_DEFINE (CONDITION_DESTROY, "condition destroy failed");
 
-/**
- * Initialize a condition variable
- * @param self is a pointer to the condition variable to be initialized
- * @return self as given
- */
+
 LumieraCondition
 lumiera_condition_init (LumieraCondition self)
 {
@@ -45,11 +41,6 @@ lumiera_condition_init (LumieraCondition self)
 }
 
 
-/**
- * Destroy a condition variable
- * @param self is a pointer to the condition variable to be destroyed
- * @return self as given
- */
 LumieraCondition
 lumiera_condition_destroy (LumieraCondition self)
 {
diff --git a/src/lib/condition.h b/src/lib/condition.h
index dd92f326b..8aea75100 100644
--- a/src/lib/condition.h
+++ b/src/lib/condition.h
@@ -44,10 +44,20 @@ typedef struct lumiera_condition_struct lumiera_condition;
 typedef lumiera_condition* LumieraCondition;
 
 
+/**
+ * Initialize a condition variable
+ * @param self is a pointer to the condition variable to be initialized
+ * @return self as given
+ */
 LumieraCondition
 lumiera_condition_init (LumieraCondition self);
 
 
+/**
+ * Destroy a condition variable
+ * @param self is a pointer to the condition variable to be destroyed
+ * @return self as given
+ */
 LumieraCondition
 lumiera_condition_destroy (LumieraCondition self);
 
diff --git a/src/lib/references.c b/src/lib/references.c
index 925258377..18c01edec 100644
--- a/src/lib/references.c
+++ b/src/lib/references.c
@@ -33,15 +33,6 @@
  */
 
 
-/**
- * Construct an initial strong reference from an object.
- * For every object which should be managed with references you need to construct an initial strong reference
- * which then will be used to initialize all further references.
- * @param self pointer to the reference to be initialized
- * @param obj pointer to the object being referenced
- * @param dtor destructor function which will be called on obj when the last strong reference gets deleted
- * @return self as given
- */
 LumieraReference
 lumiera_reference_strong_init_once (LumieraReference self, void* obj, void (*dtor)(void*))
 {
@@ -58,15 +49,7 @@ lumiera_reference_strong_init_once (LumieraReference self, void* obj, void (*dto
   return self;
 }
 
-/**
- * Destroy a reference.
- * All references need to be destroyed when not used any more.
- * When the last strong reference gets destroyed, the object's destructor is called.
- * Remaining weak references stay invalidated then until they get destroyed too.
- * @param self reference to be destroyed
- * @return self as given
- * destroying a reference is not thread safe as far as 2 threads try to concurrently destroy it!
- */
+
 LumieraReference
 lumiera_reference_destroy (LumieraReference self)
 {
@@ -113,12 +96,7 @@ lumiera_reference_destroy (LumieraReference self)
   return self;
 }
 
-/**
- * Copy construct a reference as strong reference
- * @param source reference to copy
- * @return self as strong reference (always for strong references) or NULL if source is an invalidated weak reference,
- * in the later case the reference is constructed as weak reference barely to allow it be destroyed
- */
+
 LumieraReference
 lumiera_reference_strong_init (LumieraReference self, LumieraReference source)
 {
@@ -141,11 +119,7 @@ lumiera_reference_strong_init (LumieraReference self, LumieraReference source)
   return self;
 }
 
-/**
- * Copy construct a reference as weak reference
- * @param source reference to copy
- * @return self (always for strong references) or NULL if self is an invalidated weak reference
- */
+
 LumieraReference
 lumiera_reference_weak_init (LumieraReference self, LumieraReference source)
 {
@@ -164,12 +138,7 @@ lumiera_reference_weak_init (LumieraReference self, LumieraReference source)
   return self;
 }
 
-/**
- * turn a (strong) reference into a weak reference
- * Weaken a reference may remove its last strong reference and thus destroy the object
- * do nothing if the referene is already weak
- * @return self or NULL if the final strong reference got removed,
- */
+
 LumieraReference
 lumiera_reference_weaken (restrict LumieraReference self)
 {
@@ -194,11 +163,6 @@ lumiera_reference_weaken (restrict LumieraReference self)
 }
 
 
-/**
- * turn a (weak) reference into a strong reference
- * only references of object which are not already destroyed can be strengthened
- * @return self when successful, NULL when the object was already destroyed, 'self' stays a dead weak reference in that case
- */
 LumieraReference
 lumiera_reference_strengthen (LumieraReference self)
 {
diff --git a/src/lib/references.h b/src/lib/references.h
index 6ad65d62f..3e9bf01fe 100644
--- a/src/lib/references.h
+++ b/src/lib/references.h
@@ -69,10 +69,28 @@ lumiera_reference_ensuredestroyed (LumieraReference self)
 }
 
 
+/**
+ * Construct an initial strong reference from an object.
+ * For every object which should be managed with references you need to construct an initial strong reference
+ * which then will be used to initialize all further references.
+ * @param self pointer to the reference to be initialized
+ * @param obj pointer to the object being referenced
+ * @param dtor destructor function which will be called on obj when the last strong reference gets deleted
+ * @return self as given
+ */
 LumieraReference
 lumiera_reference_strong_init_once (LumieraReference self, void* obj, void (*dtor)(void*));
 
 
+/**
+ * Destroy a reference.
+ * All references need to be destroyed when not used any more.
+ * When the last strong reference gets destroyed, the object's destructor is called.
+ * Remaining weak references stay invalidated then until they get destroyed too.
+ * @param self reference to be destroyed
+ * @return self as given
+ * destroying a reference is not thread safe as far as 2 threads try to concurrently destroy it!
+ */
 LumieraReference
 lumiera_reference_destroy (LumieraReference self);
 
@@ -88,18 +106,40 @@ lumiera_reference_get (LumieraReference self)
 }
 
 
+/**
+ * Copy construct a reference as strong reference
+ * @param source reference to copy
+ * @return self as strong reference (always for strong references) or NULL if source is an invalidated weak reference,
+ * in the later case the reference is constructed as weak reference barely to allow it be destroyed
+ */
 LumieraReference
 lumiera_reference_strong_init (LumieraReference self, LumieraReference source);
 
 
+/**
+ * Copy construct a reference as weak reference
+ * @param source reference to copy
+ * @return self (always for strong references) or NULL if self is an invalidated weak reference
+ */
 LumieraReference
 lumiera_reference_weak_init (LumieraReference self, LumieraReference source);
 
 
+/**
+ * turn a (strong) reference into a weak reference
+ * Weaken a reference may remove its last strong reference and thus destroy the object
+ * do nothing if the referene is already weak
+ * @return self or NULL if the final strong reference got removed,
+ */
 LumieraReference
 lumiera_reference_weaken (restrict LumieraReference self);
 
 
+/**
+ * turn a (weak) reference into a strong reference
+ * only references of object which are not already destroyed can be strengthened
+ * @return self when successful, NULL when the object was already destroyed, 'self' stays a dead weak reference in that case
+ */
 LumieraReference
 lumiera_reference_strengthen (LumieraReference self);
 

From 14b9847a69df93942d2143cd2036216aa793c4c9 Mon Sep 17 00:00:00 2001
From: Mano Stienen <manostienen@gmail.com>
Date: Sat, 19 Jul 2008 14:47:03 +0200
Subject: [PATCH 4/5] moved documentation from plugin.c to .h and cleaned
 documentation from safelib.c that already existed in .h

---
 src/lib/plugin.c   | 20 ------------------
 src/lib/plugin.h   | 20 ++++++++++++++++++
 src/lib/safeclib.c | 52 ----------------------------------------------
 3 files changed, 20 insertions(+), 72 deletions(-)

diff --git a/src/lib/plugin.c b/src/lib/plugin.c
index 1f5e8576e..44cf6abc5 100644
--- a/src/lib/plugin.c
+++ b/src/lib/plugin.c
@@ -111,10 +111,6 @@ lumiera_plugin_name_cmp (const void* a, const void* b)
   return strcmp (((struct lumiera_plugin*) a)->name, ((struct lumiera_plugin*) b)->name);
 }
 
-/**
- * Initialize the plugin system.
- * always succeeds or aborts
- */
 void
 lumiera_init_plugin (void)
 {
@@ -173,17 +169,6 @@ lumiera_plugin_lookup (struct lumiera_plugin* self, const char* path)
 }
 
 
-/**
- * Make an interface available.
- * To use an interface provided by a plugin it must be opened first. It is allowed to open an interface 
- * more than once. Each open must be paired with a close.
- * @param name name of the plugin to use.
- * @param interface name of the interface to open.
- * @param min_revision the size of the interface structure is used as measure of a minimal required 
- * revision (new functions are appended at the end)
- * @return handle to the interface or NULL in case of a error. The application shall cast this handle to
- * the actual interface type.
- */
 struct lumiera_interface*
 lumiera_interface_open (const char* name, const char* interface, size_t min_revision)
 {
@@ -311,11 +296,6 @@ lumiera_interface_open (const char* name, const char* interface, size_t min_revi
   return NULL;
 }
 
-/**
- * Close an interface. Does not free associated resources
- * Calling this function with self==NULL is legal. Every interface handle must be closed only once.
- * @param ptr interface to be closed
- */
 void
 lumiera_interface_close (void* ptr)
 {
diff --git a/src/lib/plugin.h b/src/lib/plugin.h
index 54dad6372..7e17afc18 100644
--- a/src/lib/plugin.h
+++ b/src/lib/plugin.h
@@ -96,14 +96,34 @@ struct lumiera_interface
   int (*close)(void);
 };
 
+/**
+ * Initialize the plugin system.
+ * always succeeds or aborts
+ */
 void
 lumiera_init_plugin (void);
 
 
+/**
+ * Make an interface available.
+ * To use an interface provided by a plugin it must be opened first. It is allowed to open an interface 
+ * more than once. Each open must be paired with a close.
+ * @param name name of the plugin to use.
+ * @param interface name of the interface to open.
+ * @param min_revision the size of the interface structure is used as measure of a minimal required 
+ * revision (new functions are appended at the end)
+ * @return handle to the interface or NULL in case of a error. The application shall cast this handle to
+ * the actual interface type.
+ */
 struct lumiera_interface*
 lumiera_interface_open (const char* plugin, const char* name, size_t min_revision);
 
 
+/**
+ * Close an interface. Does not free associated resources
+ * Calling this function with self==NULL is legal. Every interface handle must be closed only once.
+ * @param ptr interface to be closed
+ */
 void
 lumiera_interface_close (void* self);
 
diff --git a/src/lib/safeclib.c b/src/lib/safeclib.c
index f500ea71c..4a19477c1 100644
--- a/src/lib/safeclib.c
+++ b/src/lib/safeclib.c
@@ -26,19 +26,9 @@
 #include <stdint.h>
 #include <stdarg.h>
 
-/**
- * @file
- * Portable and safe wrapers around some clib functions and some tools
- */
 
 LUMIERA_ERROR_DEFINE (NO_MEMORY, "Out of Memory!");
 
-/**
- * Allocate memory.
- * always succeeds or dies
- * @param size memory to be allocated
- * @return pointer to the allocated memory
- */
 void*
 lumiera_malloc (size_t size)
 {
@@ -49,13 +39,6 @@ lumiera_malloc (size_t size)
 }
 
 
-/**
- * Allocate cleared memory for an array.
- * always succeeds or dies
- * @param n number of elements
- * @param size memory to be allocated
- * @return pointer to the allocated memory
- */
 void*
 lumiera_calloc (size_t n, size_t size)
 {
@@ -66,13 +49,6 @@ lumiera_calloc (size_t n, size_t size)
 }
 
 
-/**
- * Duplicate a C string.
- * always succeeds or dies
- * @param str string to be copied
- * @param len maximal length to be copied
- * @return pointer to the new string, "" if NULL was passed as str
- */
 char*
 lumiera_strndup (const char* str, size_t len)
 {
@@ -88,14 +64,6 @@ lumiera_strndup (const char* str, size_t len)
 }
 
 
-/**
- * Compare two C strings.
- * Handles NULL pointers as "", shortcut for same addresses
- * @param a first string for comparsion
- * @param b second string for comparsion
- * @param len maximal length for the comparsion
- * @return 0 if the strings are identical, -1 if smaller 1 if bigger.
- */
 int
 lumiera_strncmp (const char* a, const char* b, size_t len)
 {
@@ -103,12 +71,6 @@ lumiera_strncmp (const char* a, const char* b, size_t len)
 }
 
 
-/**
- * check 2 strings for identity.
- * @param a first string for comparsion
- * @param b second string for comparsion
- * @return 1 when the strings are the the same, 0 if not.
- */
 int
 lumiera_streq (const char* a, const char* b)
 {
@@ -116,11 +78,6 @@ lumiera_streq (const char* a, const char* b)
 }
 
 
-/**
- * Round robin temporary buffers.
- * This provides 64 buffers per thread which are recycled with each use.
- * The idea here is to have fast buffers for temporal data without need for explicit heap management.
- */
 struct lumiera_tmpbuf_struct
 {
   void* buffers[64];
@@ -147,10 +104,6 @@ lumiera_tmpbuf_init (void)
 }
 
 
-/**
- * free all buffers associated with this thread.
- * This function is called automatically, usually one doesnt need to call it.
- */
 void
 lumiera_tmpbuf_freeall (void)
 {
@@ -166,11 +119,6 @@ lumiera_tmpbuf_freeall (void)
 }
 
 
-/**
- * Query a thread local buffer.
- * @param size minimal needed size for the buffer
- * @return the buffer
- */
 void*
 lumiera_tmpbuf_provide (size_t size)
 {

From 163ba179ed93c49c6d331c16afe9e54e97ad1876 Mon Sep 17 00:00:00 2001
From: Mano Stienen <manostienen@gmail.com>
Date: Sun, 20 Jul 2008 16:11:08 +0200
Subject: [PATCH 5/5] moved documentation from error.c to .h

---
 src/lib/error.c | 14 +-------------
 src/lib/error.h | 13 +++++++++++++
 2 files changed, 14 insertions(+), 13 deletions(-)

diff --git a/src/lib/error.c b/src/lib/error.c
index b2bc390b6..dc9acfa56 100644
--- a/src/lib/error.c
+++ b/src/lib/error.c
@@ -45,13 +45,7 @@ lumiera_error_tls_init (void)
   pthread_key_create (&lumiera_error_tls, NULL);
 }
 
-/**
- * Set error state for the current thread.
- * If the error state of the current thread was cleared, then set it, else preserve the old state.
- * @param nerr name of the error with 'LUMIERA_ERROR_' prefix (example: LUMIERA_ERROR_NO_MEMORY)
- * @return old state, that is NULL for success, when the state was cleared and a pointer to a pending 
- * error when the error state was already set
- */
+
 const char*
 lumiera_error_set (const char * nerr)
 {
@@ -65,12 +59,6 @@ lumiera_error_set (const char * nerr)
 }
 
 
-/**
- * Get and clear current error state.
- * This function clears the error state, if it needs to be reused, one has to store it in a temporary
- * variable.
- * @return pointer to any pending error of this thread, NULL if no error is pending
- */
 const char*
 lumiera_error ()
 {
diff --git a/src/lib/error.h b/src/lib/error.h
index 1eeb42dda..e00e69c6b 100644
--- a/src/lib/error.h
+++ b/src/lib/error.h
@@ -70,9 +70,22 @@ const char* LUMIERA_ERROR_##err = "LUMIERA_ERROR_" #err ":" msg
 (({ERROR (flag, "%s", strchr(LUMIERA_ERROR_##err, ':')+1);}), \
 lumiera_error_set(LUMIERA_ERROR_##err))
 
+/**
+ * Set error state for the current thread.
+ * If the error state of the current thread was cleared, then set it, else preserve the old state.
+ * @param nerr name of the error with 'LUMIERA_ERROR_' prefix (example: LUMIERA_ERROR_NO_MEMORY)
+ * @return old state, that is NULL for success, when the state was cleared and a pointer to a pending 
+ * error when the error state was already set
+ */
 const char*
 lumiera_error_set (const char * err);
 
+/**
+ * Get and clear current error state.
+ * This function clears the error state, if it needs to be reused, one has to store it in a temporary
+ * variable.
+ * @return pointer to any pending error of this thread, NULL if no error is pending
+ */
 const char*
 lumiera_error ();