From c2f5665e5657e4efec1a64551e6f60e88cc2fbfe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Odin=20Omdal=20H=C3=B8rthe?= <odin.horthe@gmail.com>
Date: Sat, 20 Oct 2007 18:10:35 +0200
Subject: [PATCH] More doxygen documenting in src/lib/. Some name fixes, some
 new docs.

---
 src/lib/rwlock.c |  2 +-
 src/lib/time.h   | 35 +++++++++++++++++++++++++++++++++--
 2 files changed, 34 insertions(+), 3 deletions(-)

diff --git a/src/lib/rwlock.c b/src/lib/rwlock.c
index a2de75be8..48becb14d 100644
--- a/src/lib/rwlock.c
+++ b/src/lib/rwlock.c
@@ -68,7 +68,7 @@ cinelerra_rwlock_destroy (CinelerraRWLock self)
 /**
  * initialize a rwlockacquirer state
  * @param self rwlockacquirer to be initialized, must be an automatic variable
- * @param cond associated rwlock
+ * @param rwlock associated rwlock
  * @param state initial state of the mutex, either CINELERRA_RDLOCKED, CINELERRA_WRLOCKED or CINELERRA_UNLOCKED
  * @return self as given or NULL on error
  */
diff --git a/src/lib/time.h b/src/lib/time.h
index 34c0035e4..4203ece49 100644
--- a/src/lib/time.h
+++ b/src/lib/time.h
@@ -31,9 +31,13 @@
 /*
  * @file Time calculations.
   this time functions are small macro like wrapers, they are all inlined for performance reasons
-  time is passed around as pointers, this pointer must never be NULL
+  time is passed around as pointers, this pointer must never be NULL.
 
-  timehandling is a delicate business, be careful of precision errors accumulating, TODO explain how to use time
+  timehandling is a delicate business, be careful of precision errors accumulating
+
+  cinelerra_time is starting from zero, never becomes negative.
+  
+  TODO explain how to use time
 
 */
 
@@ -68,6 +72,8 @@ cinelerra_time_normalize (CinelerraTime time)
 
 /**
  * set a time value to zero.
+ * @param time Time to clear
+ * @return time as given
  */
 static inline CinelerraTime
 cinelerra_time_clear (CinelerraTime time)
@@ -82,6 +88,8 @@ cinelerra_time_clear (CinelerraTime time)
 
 /**
  * get current time.
+ * @param time Time to put current time into.
+ * @return time as given
  */
 static inline CinelerraTime
 cinelerra_time_current (CinelerraTime time)
@@ -97,6 +105,10 @@ cinelerra_time_current (CinelerraTime time)
 
 /**
  * init from floating point representation.
+ * @param time The time to be set
+ * @param fp Time in double
+ * @return time as given upon success, NULL if double time given was negative or given time didn't point
+ * anywhere
  */
 static inline CinelerraTime
 cinelerra_time_set_double (CinelerraTime time, double fp)
@@ -121,6 +133,10 @@ cinelerra_time_set_double (CinelerraTime time, double fp)
 
 /**
  * initialize with seconds and microseconds.
+ * @param time Time to set
+ * @param sec Seconds to set
+ * @param usec Microseconds to set
+ * @param Time as given
  */
 static inline CinelerraTime
 cinelerra_time_init (CinelerraTime time, time_t sec, suseconds_t usec)
@@ -136,6 +152,8 @@ cinelerra_time_init (CinelerraTime time, time_t sec, suseconds_t usec)
 
 /**
  * get the seconds part from a time.
+ * @param time Time to get seconds from
+ * @return Seconds elapsed, -1 on error
  */
 static inline time_t
 cinelerra_time_sec (CinelerraTime time)
@@ -148,6 +166,8 @@ cinelerra_time_sec (CinelerraTime time)
 
 /**
  * get the microseconds part of a time.
+ * @param time Time to get microseconds from
+ * @return Microseconds elapsed, -1 on error
  */
 static inline suseconds_t
 cinelerra_time_usec (CinelerraTime time)
@@ -160,6 +180,8 @@ cinelerra_time_usec (CinelerraTime time)
 
 /**
  * convert to floating point repesentation.
+ * @param time Time to get floating point representation from
+ * @return Floating point representation of time. NAN on error.
  */
 static inline double
 cinelerra_time_double_get (CinelerraTime time)
@@ -178,6 +200,9 @@ cinelerra_time_double_get (CinelerraTime time)
 
 /**
  * copy time
+ * @param dest Time-pointer to copy to
+ * @param src Time-source to copy from
+ * @return dest as given
  */
 static inline CinelerraTime
 cinelerra_time_copy (CinelerraTime dest, const CinelerraTime src)
@@ -192,6 +217,9 @@ cinelerra_time_copy (CinelerraTime dest, const CinelerraTime src)
 
 /**
  * add time.
+ * @param dest The result of the add
+ * @param src Time to add to dest
+ * @return dest as given, or NULL on overflow.
  */
 static inline CinelerraTime
 cinelerra_time_add (CinelerraTime dest, const CinelerraTime src)
@@ -216,6 +244,9 @@ cinelerra_time_add (CinelerraTime dest, const CinelerraTime src)
 
 /**
  * substact time.
+ * @param dest The result of subtract
+ * @param src Time to subtract from dest
+ * @return dest as given, or NULL on underflow.
  */
 static inline CinelerraTime
 cinelerra_time_sub (CinelerraTime dest, const CinelerraTime src)