From faa433a7897a4f14eb903e95d8ad515b8f204018 Mon Sep 17 00:00:00 2001
From: "Jonas M. Gastal" <jgastal@profusion.mobi>
Date: Fri, 9 Mar 2012 19:21:52 +0000
Subject: [PATCH] Improvements to ecore timer docs.

SVN revision: 69115
---
 legacy/ecore/src/lib/ecore/Ecore.h       | 15 +++++++++++++--
 legacy/ecore/src/lib/ecore/ecore_timer.c | 15 ++++++++-------
 2 files changed, 21 insertions(+), 9 deletions(-)

diff --git a/legacy/ecore/src/lib/ecore/Ecore.h b/legacy/ecore/src/lib/ecore/Ecore.h
index 78b2078a0d..1ed0d1156a 100644
--- a/legacy/ecore/src/lib/ecore/Ecore.h
+++ b/legacy/ecore/src/lib/ecore/Ecore.h
@@ -1246,9 +1246,20 @@ EAPI double ecore_loop_time_get(void);
 /**
  * @defgroup Ecore_Timer_Group Ecore Timer functions
  *
- * Functions to create events based on timers.
+ * Ecore provides very flexible timer functionality. The basic usage of timers,
+ * to call a certain function at a certain interval can be achieved with a
+ * single line:
+ * @code
+ * Eina_Bool my_func(void *data) {
+ *    do_funky_stuff_with_data(data);
+ *    return EINA_TRUE;
+ * }
+ * ecore_timer_add(interval_in_seconds, my_func, data_given_to_function);
+ * @endcode
+ * @note If the function was to be executed only once simply return EINA_FALSE
+ * instead.
  *
- * Examples:
+ * An example that shows the usage of a lot of these:
  * @li @ref ecore_timer_example_c
  *
  * @ingroup Ecore_Main_Loop_Group
diff --git a/legacy/ecore/src/lib/ecore/ecore_timer.c b/legacy/ecore/src/lib/ecore/ecore_timer.c
index 1383e019e4..d76733b4bb 100644
--- a/legacy/ecore/src/lib/ecore/ecore_timer.c
+++ b/legacy/ecore/src/lib/ecore/ecore_timer.c
@@ -73,12 +73,15 @@ ecore_timer_precision_get(void)
 }
 
 /**
- * Sets the precision to be used by timer infrastructure.
+ * @brief Sets the precision to be used by timer infrastructure.
  *
- * When system calculates time to expire the next timer we'll be able
- * to delay the timer by the given amount so more timers will fit in
- * the same dispatch, waking up the system less often and thus being
- * able to save power.
+ * @param value allowed introduced timeout delay, in seconds.
+ *
+ * This sets the precision for @b all timers. The precision determines how much
+ * of an difference from the requested interval is acceptable. One common reason
+ * to use this function is to @b increase the allowed timeout and thus @b
+ * decrease precision of the timers, this is because less precise the timers
+ * result in the system waking up less often and thus consuming less resources.
  *
  * Be aware that kernel may delay delivery even further, these delays
  * are always possible due other tasks having higher priorities or
@@ -93,8 +96,6 @@ ecore_timer_precision_get(void)
  * @note Ecore is smart enough to see if there are timers in the
  * precision range, if it does not, in our example if no second timer
  * in (T + precision) existed, then it would use the minimum timeout.
- *
- * @param value allowed introduced timeout delay, in seconds.
  */
 EAPI void
 ecore_timer_precision_set(double value)