efl: add documentation and last cleanup of the API.

src/lib/ecore/efl_promise.c

@@ -535,7 +535,7 @@ _efl_promise_value_set(Eo *obj, Efl_Promise_Data *pd, void *v, Eina_Free_Cb free
 }
 
 static void
-_efl_promise_failed(Eo *obj, Efl_Promise_Data *pd, Eina_Error err)
+_efl_promise_failed_set(Eo *obj, Efl_Promise_Data *pd, Eina_Error err)
 {
    Efl_Promise_Msg *message;
    Efl_Loop_Future_Data *f;
@@ -576,7 +576,7 @@ _efl_promise_failed(Eo *obj, Efl_Promise_Data *pd, Eina_Error err)
 }
 
 static void
-_efl_promise_progress_set(Eo *obj, Efl_Promise_Data *pd, void *p)
+_efl_promise_progress_set(Eo *obj, Efl_Promise_Data *pd, const void *p)
 {
    Efl_Loop_Future_Data *f;
    Eina_List *l, *ln;
@@ -620,7 +620,7 @@ _efl_promise_efl_object_destructor(Eo *obj, Efl_Promise_Data *pd)
    if (!pd->message && pd->futures)
      {
         if (!pd->optional) ERR("This promise has not been fulfilled. Forcefully cancelling %p.", obj);
-        efl_promise_failed(obj, EINA_ERROR_FUTURE_CANCEL);
+        efl_promise_failed_set(obj, EINA_ERROR_FUTURE_CANCEL);
      }
 
    if (pd->message)
@@ -916,7 +916,7 @@ _fail_all(void *data, const Efl_Event *ev)
           }
      }
 
-   efl_promise_failed(all->promise, fail->error);
+   efl_promise_failed_set(all->promise, fail->error);
    _efl_promise_all_free(all);
    efl_unref(all->promise);
 }
@@ -1128,7 +1128,7 @@ _fail_race(void *data, const Efl_Event *ev)
           }
      }
 
-   efl_promise_failed(race->promise, fail->error);
+   efl_promise_failed_set(race->promise, fail->error);
    _efl_promise_all_free(race);
    efl_unref(race->promise);
 }

src/lib/ecore/efl_promise.eo

@@ -3,32 +3,53 @@ import eina_types;
 class Efl.Promise (Efl.Loop_User)
 {
    methods {
-      @property progress {
-         set {
-         }
-         values {
-            p: void_ptr;
+      progress_set {
+         [[Update the progress and send it immediately to all connected Efl_Future.
+
+           The progress is not kept and when the function return it will not be accessed
+           anymore. The pointer is owned by the caller and will remain so after the return
+	   of the function call.
+	 ]]
+         params {
+            @in p: const(void_ptr);
 	 }
       }
       @property future {
+         [[Request a new future linked to this promise.
+
+	   Efl_Future are optional and will be automatically deleted if no then callback have
+	   been set before the next iteration of the main loop.
+	 ]]
          get {
-	    [[The returned future is optional and if no then/chain_then are registered before it goes back to run in the main loop, it will be destroyed.]]
+	    [[The returned new future.]]
          }
          values {
-            f: future<void_ptr>;
+            f: future<void_ptr, void_ptr>; [[Return a future where the value will be set by calling value_set while the progress will be updated by progress_set.]]
          }
       }
       @property value {
+      	 [[The value expected by all connected future.]]
          set {
+	    [[
+              This function can be called only once and you can not call #failed.set after that.
+              The value will be owned by the promise until it is destroyed. The value will be cleaned
+              when the promise and all the future depending on it are destroyed.
+            ]]
 	 }
 	 values {
-	    v: void_ptr;
-	    free_cb: __builtin_free_cb;
+	    v: void_ptr; [[The pointer to the value.]]
+	    free_cb: __builtin_free_cb; [[The function to call to free the value.]]
 	 }
       }
-      failed {
-         params {
-	    @in err: Eina.Error;
+      @property failed {
+         [[Define the failure state of this promise.]]
+	 set {
+	    [[
+              This function can be called only once and you can not call #value.set after that.
+	    ]]
+	 }
+         values {
+	    err: Eina.Error; [[The reason for failure of this promise.]]
          }
       }
    }

src/lib/eio/efl_io_manager.c

@@ -111,7 +111,7 @@ _file_error_cb(void *data, Eio_File *handler, int error)
 
    efl_event_callback_array_del(p, promise_handling(), handler);
 
-   efl_promise_failed(p, error);
+   efl_promise_failed_set(p, error);
 
    efl_del(p);
 }
@@ -126,7 +126,7 @@ _file_done_cb(void *data, Eio_File *handler)
 
    if (!v)
      {
-        efl_promise_failed(p, ENOMEM);
+        efl_promise_failed_set(p, ENOMEM);
         goto end;
      }
 
@@ -365,7 +365,7 @@ _file_stat_done_cb(void *data, Eio_File *handle EINA_UNUSED, const Eina_Stat *st
    c = calloc(1, sizeof (Eina_Stat));
    if (!c)
      {
-        efl_promise_failed(p, ENOMEM);
+        efl_promise_failed_set(p, ENOMEM);
         goto end;
      }
 

src/lib/eo/efl_future.h

@@ -15,36 +15,65 @@ typedef Eo Efl_Promise;
 #define EFL_FUTURE_CLASS efl_future_class_get()
 EWAPI const Efl_Class *efl_future_class_get(void);
 
+/**
+ * @var EINA_ERROR_FUTURE_CANCEL
+ * @brief The error identifier corresponding to a future being canceled.
+ */
 EAPI extern Eina_Error EINA_ERROR_FUTURE_CANCEL;
 
+/** Parameter passed in event callbacks in case of future failure to proceed.
+ *
+ * @ingroup Efl_Future
+ */
 typedef struct _Efl_Future_Event_Failure Efl_Future_Event_Failure;
 struct _Efl_Future_Event_Failure
 {
-   Efl_Promise *next;
-   Eina_Error error;
+   Efl_Promise *next; /** The promise to the next future. Allowing to send a processed value down the chain. */
+   Eina_Error error; /** The error generated trying to process the request. */
 };
 
+/** Parameter passed in event callbacks in case of future succeeding to proceed.
+ *
+ * @ingroup Efl_Future
+ */
 typedef struct _Efl_Future_Event_Success Efl_Future_Event_Success;
 struct _Efl_Future_Event_Success
 {
-   Efl_Promise *next;
-   void *value;
+   Efl_Promise *next; /** The promise to the next future. Allowing to send a processed value down the chain. */
+   void *value; /** The value return by the processed request. The type is defined by the function executing the request. */
 };
 
+/** Parameter passed in event callbacks while a future is progressing a request.
+ *
+ * @ingroup Efl_Future
+ */
 typedef struct _Efl_Future_Event_Progress Efl_Future_Event_Progress;
 struct _Efl_Future_Event_Progress
 {
-   Efl_Promise *next;
-   void *progress;
+   Efl_Promise *next;  /** The promise to the next future. Allowing to send a processed progress down the chain. */
+   const void *progress; /** The progress status updated by the processed request. The type is defined by the function executing the request. */
 };
 
 EOAPI extern const Efl_Event_Description _EFL_FUTURE_EVENT_FAILURE;
 EOAPI extern const Efl_Event_Description _EFL_FUTURE_EVENT_SUCCESS;
 EOAPI extern const Efl_Event_Description _EFL_FUTURE_EVENT_PROGRESS;
 
-  // FIXME: documentation
+/** A future failed
+ *
+ * @ingroup Efl_Future
+ */
 #define EFL_FUTURE_EVENT_FAILURE (&(_EFL_FUTURE_EVENT_FAILURE))
+
+/** A future succeeded
+ *
+ * @ingroup Efl_Future
+ */
 #define EFL_FUTURE_EVENT_SUCCESS (&(_EFL_FUTURE_EVENT_SUCCESS))
+
+/** A future progressed
+ *
+ * @ingroup Efl_Future
+ */
 #define EFL_FUTURE_EVENT_PROGRESS (&(_EFL_FUTURE_EVENT_PROGRESS))
 
 /**
@@ -57,7 +86,9 @@ EOAPI extern const Efl_Event_Description _EFL_FUTURE_EVENT_PROGRESS;
  * @param[in] progress the callback to call during the progression of the the promise, this is optional
  * @param[in] data additional data to pass to the callback
  *
- * @return Return a new future when the callback has been successfully added. This future can be ignored.
+ * @return Return a new future when the callback has been successfully added pointing to the next request
+ * being processed during the future success, failure or progress callback (You can reference count the next
+ * promise to defer the result and make it asynchronous too. This future can be ignored.
  *
  * @note except if you do reference count the Efl.Future object, you can only call once this function.
  *
@@ -68,7 +99,8 @@ EOAPI Efl_Future *efl_future_then(Eo *obj, Efl_Event_Cb success, Efl_Event_Cb fa
 /**
  * @brief Cancel the need for that specific future.
  *
- * This will trigger the failure of the future and may result in the promise stopping its computation.
+ * This will trigger the failure of the future and may result in the promise stopping its computation as
+ * it will be notified when there is no more need for computing the request.
  *
  * @see efl_future_use
  *

src/tests/ecore/ecore_test_promise.c

@@ -605,7 +605,7 @@ _chain_fail(void *data, const Efl_Event *ev)
 
    fo->cancel = EINA_TRUE;
 
-   efl_promise_failed(f->next, f->error);
+   efl_promise_failed_set(f->next, f->error);
 }
 
 static void