From e28bf92b2857ff1d4971d8ff9b213bad2078b511 Mon Sep 17 00:00:00 2001
From: Marcel Hollerbach <mail@marcel-hollerbach.de>
Date: Wed, 20 Feb 2019 14:14:13 +0100
Subject: [PATCH] efl_loop: document and annotate efl_loop_time correctly

this adds over the documentation of the legacy header.
Additionally set is defined as protected.

ref T7597
---
 src/lib/ecore/ecore_time.c |  2 ++
 src/lib/ecore/efl_loop.c   |  2 ++
 src/lib/ecore/efl_loop.eo  | 23 +++++++++++++++++++----
 3 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/src/lib/ecore/ecore_time.c b/src/lib/ecore/ecore_time.c
index c7c79b1..303295b 100644
--- a/src/lib/ecore/ecore_time.c
+++ b/src/lib/ecore/ecore_time.c
@@ -2,6 +2,8 @@
 # include <config.h>
 #endif
 
+#define EFL_LOOP_PROTECTED
+
 #include <stdlib.h>
 #include <sys/time.h>
 
diff --git a/src/lib/ecore/efl_loop.c b/src/lib/ecore/efl_loop.c
index 9c7dcfd..d49d01a 100644
--- a/src/lib/ecore/efl_loop.c
+++ b/src/lib/ecore/efl_loop.c
@@ -2,6 +2,8 @@
 # include <config.h>
 #endif
 
+#define EFL_LOOP_PROTECTED
+
 #include <stdlib.h>
 #include <stdio.h>
 #include <string.h>
diff --git a/src/lib/ecore/efl_loop.eo b/src/lib/ecore/efl_loop.eo
index 4516c4c..50e0abf 100644
--- a/src/lib/ecore/efl_loop.eo
+++ b/src/lib/ecore/efl_loop.eo
@@ -59,11 +59,26 @@ class @beta Efl.Loop extends Efl.Task
          }
       }
       @property time {
-         [[The time point when the loop was logically woken.]]
-         set {}
-         get {}
+         [[Retrieves the time at which the last loop stopped waiting for timeouts or events.]]
+         set @protected {
+           [[You should never need/call this, unless you are implementing a custom
+             tick source for an animator.
+
+             Note: The time point must match whatever zero time you get from ecore_time_get() and @.time.get() (same 0 point).
+             What this point is is undefined, so unless your source uses the same 0 time, then you may have to adjust and do some guessing.
+           ]]
+         }
+         get {
+           [[This gets the time that the main loop ceased waiting for timouts and/or
+             events to come in or for signals or any other interrupt source. This should
+             be considered a reference point for all time based activity that should
+             calculate its timepoint from the return of ecore_loop_time_get(). Note that this
+             time is meant to be used as relative to other times obtained on this run.
+             If you need absolute time references, use a unix timestamp instead.
+            ]]
+         }
          values {
-           timepoint: double; [[Time in seconds since process specific start point]]
+           timepoint: double; [[Time in seconds]]
          }
       }
       idle {
-- 
2.7.4