forked from enlightenment/efl
eina: Add doxygen in/out tags for promise
Summary: Also, add some missing param docs, and fix some incorrect ones. Reviewers: devilhorns Reviewed By: devilhorns Subscribers: cedric, #committers, zmike Tags: #efl Differential Revision: https://phab.enlightenment.org/D6698
This commit is contained in:
Bryce Harrington
Chris Michael
parent
54907b1995
commit
dc2ad11281
|
|
@ -41,14 +41,14 @@ typedef struct _Eina_Future_Cb_Log_Desc Eina_Future_Cb_Log_Desc;
|
|||
* or similar failed due to invalid pointer or memory allocation. Then the callback is called from the
|
||||
* failed context using `EINVAL` or `ENOMEM` as errors and @p dead_future will be @c NULL.
|
||||
*
|
||||
* @param data The data provided by the user
|
||||
* @param[in] data The data provided by the user
|
||||
*
|
||||
* @param value An Eina_Value which contains the operation result. Before using
|
||||
* @param[in] value An Eina_Value which contains the operation result. Before using
|
||||
* the @p value, its type must be checked in order to avoid errors. This is needed because
|
||||
* if an operation fails the Eina_Value type will be EINA_VALUE_TYPE_ERROR
|
||||
* which is a different type than the expected operation result.
|
||||
*
|
||||
* @param dead_future A pointer to the future that was completed.
|
||||
* @param[in] dead_future A pointer to the future that was completed.
|
||||
*
|
||||
* @return An Eina_Value to pass to the next Eina_Future in the chain (if any).
|
||||
* If there is no need to convert the received value, it's @b recommended
|
||||
|
|
@ -106,8 +106,8 @@ struct _Eina_Future_Schedule_Entry {
|
|||
* A callback used by the Eina_Future_Scheduler to deliver
|
||||
* the future operation result.
|
||||
*
|
||||
* @param f The delivered future.
|
||||
* @param value The future result
|
||||
* @param[out] f The delivered future.
|
||||
* @param[in] value The future result
|
||||
*
|
||||
*
|
||||
* @see eina_promise_new()
|
||||
|
|
@ -136,10 +136,10 @@ struct _Eina_Future_Scheduler {
|
|||
* @note Must not be @c NULL
|
||||
*
|
||||
* Must call back from a safe context using @p cb(f,value)
|
||||
* @param scheduler The scheduler to use.
|
||||
* @param cb The #Eina_Future_Scheduler_Cb to be called and deliver the @p f and @p value.
|
||||
* @param f The future to be delivered to @p cb
|
||||
* @param value The value to be delivered to @p cb
|
||||
* @param[in,out] scheduler The scheduler to use.
|
||||
* @param[in] cb The #Eina_Future_Scheduler_Cb to be called and deliver the @p f and @p value.
|
||||
* @param[in] f The future to be delivered to @p cb
|
||||
* @param[in] value The value to be delivered to @p cb
|
||||
* @return A scheduled entry or @c NULL on error
|
||||
*/
|
||||
Eina_Future_Schedule_Entry *(*schedule)(Eina_Future_Scheduler *scheduler, Eina_Future_Scheduler_Cb cb, Eina_Future *f, Eina_Value value);
|
||||
|
|
@ -179,8 +179,8 @@ struct _Eina_Future_Scheduler {
|
|||
* call yourself. It's only meant as cancellation, not a general
|
||||
* "free callback".
|
||||
*
|
||||
* @param data The data provided by the user.
|
||||
* @param dead_promise The canceled promise.
|
||||
* @param[in] data The data provided by the user.
|
||||
* @param[in] dead_promise The canceled promise.
|
||||
* @see eina_promise_reject()
|
||||
* @see eina_promise_resolve()
|
||||
* @see eina_future_cancel()
|
||||
|
|
@ -201,8 +201,8 @@ typedef void (*Eina_Promise_Cancel_Cb) (void *data, const Eina_Promise *dead_pro
|
|||
*
|
||||
* @note This function is always called from a safe context (main loop or some platform defined safe context).
|
||||
*
|
||||
* @param data The data provided by the user.
|
||||
* @param value The operation result
|
||||
* @param[in] data The data provided by the user.
|
||||
* @param[in] value The operation result
|
||||
* @return An Eina_Value to pass to the next Eina_Future in the chain (if any).
|
||||
* If there is no need to convert the received value, it's @b recommended
|
||||
* to pass-thru @p value argument. If you need to convert to a different type
|
||||
|
|
@ -239,8 +239,8 @@ typedef Eina_Value (*Eina_Future_Success_Cb)(void *data, const Eina_Value value)
|
|||
* if an Eina_Value type EINA_VALUE_TYPE_ERROR is returned the error will continue to be reported
|
||||
* to the other futures in the chain.
|
||||
*
|
||||
* @param data The data provided by the user.
|
||||
* @param error The operation error
|
||||
* @param[in] data The data provided by the user.
|
||||
* @param[in] error The operation error
|
||||
* @return An Eina_Value to pass to the next Eina_Future in the chain (if any).
|
||||
* If you need to convert to a different type or generate a new value,
|
||||
* use @c eina_value_setup() on @b another Eina_Value
|
||||
|
|
@ -268,8 +268,8 @@ typedef Eina_Value (*Eina_Future_Error_Cb)(void *data, const Eina_Error error);
|
|||
* @note This callback is always called, even if #Eina_Future_Error_Cb and/or #Eina_Future_Success_Cb
|
||||
* were not provided, which can also be used to monitor when a future ends.
|
||||
*
|
||||
* @param data The data provided by the user.
|
||||
* @param dead_future The future that was freed.
|
||||
* @param[in] data The data provided by the user.
|
||||
* @param[in] dead_future The future that was freed.
|
||||
*
|
||||
* @see eina_future_cb_easy_from_desc()
|
||||
* @see eina_future_cb_easy()
|
||||
|
|
@ -525,9 +525,10 @@ struct _Eina_Future_Desc {
|
|||
* resolve to it directly use the eina_future_resolved(), it has the
|
||||
* same effect as creating a promise and immediately resolving it.
|
||||
*
|
||||
* @param cancel_cb A callback used to inform that the promise was canceled. Use
|
||||
* @param[in,out] scheduler The scheduler.
|
||||
* @param[in] cancel_cb A callback used to inform that the promise was canceled. Use
|
||||
* this callback to @c free @p data. @p cancel_cb must not be @c NULL !
|
||||
* @param data Data to @p cancel_cb.
|
||||
* @param[in] data Data to @p cancel_cb.
|
||||
* @return A promise or @c NULL on error.
|
||||
* @see eina_future_cancel()
|
||||
* @see eina_future_new()
|
||||
|
|
@ -591,10 +592,10 @@ EAPI Eina_Promise *eina_promise_new(Eina_Future_Scheduler *scheduler, Eina_Promi
|
|||
* @note This function is to be used solely inside of a future resolve callback with
|
||||
* the Eina_Value being returned from it.
|
||||
*
|
||||
* @param dead_future The future being resolved to get a scheduler from.
|
||||
* @param cancel_cb A callback used to inform that the promise was canceled. Use
|
||||
* @param[in] dead_future The future being resolved to get a scheduler from.
|
||||
* @param[in] cancel_cb A callback used to inform that the promise was canceled. Use
|
||||
* this callback to @c free @p data. @p cancel_cb must not be @c NULL !
|
||||
* @param data Data to @p cancel_cb.
|
||||
* @param[in] data Data to @p cancel_cb.
|
||||
* @return A promise or @c NULL on error.
|
||||
* @see eina_future_cancel()
|
||||
* @see eina_future_new()
|
||||
|
|
@ -634,8 +635,10 @@ EAPI void eina_promise_data_set(Eina_Promise *p, void *data) EINA_ARG_NONNULL(1)
|
|||
* safe context (main loop or some platform defined safe context),
|
||||
* whenever possible the future callbacks will be dispatched.
|
||||
*
|
||||
* @param p A promise to resolve.
|
||||
* @param value The value to be delivered. Note that the value contents must survive this function scope,
|
||||
* @param[in,out] p A promise to resolve.
|
||||
* @param[in] value The value to be delivered.
|
||||
*
|
||||
* Note that the @p value contents must survive this function scope,
|
||||
* that is, do @b not use stack allocated blobs, arrays, structures or types that
|
||||
* keep references to memory you give. Values will be automatically cleaned up
|
||||
* using @c eina_value_flush() once they are unused (no more future or futures
|
||||
|
|
@ -655,8 +658,8 @@ EAPI void eina_promise_resolve(Eina_Promise *p, Eina_Value value) EINA_ARG_NONNU
|
|||
* safe context (main loop or some platform defined safe context),
|
||||
* whenever possible the future callbacks will be dispatched.
|
||||
*
|
||||
* @param p A promise to reject.
|
||||
* @param err An Eina_Error value
|
||||
* @param[in,out] p A promise to reject.
|
||||
* @param[in] err An Eina_Error value
|
||||
* @note Internally this function will create an Eina_Value with type #EINA_VALUE_TYPE_ERROR.
|
||||
*
|
||||
* @see eina_promise_new()
|
||||
|
|
@ -679,7 +682,7 @@ EAPI void eina_promise_reject(Eina_Promise *p, Eina_Error err) EINA_ARG_NONNULL(
|
|||
* and it will also cancel the promise linked against it. The Eina_Future_Cb will be called
|
||||
* with an Eina_Value typed as #EINA_VALUE_TYPE_ERROR, which its value will be
|
||||
* ECANCELED
|
||||
* @param f The future to cancel.
|
||||
* @param[in,out] f The future to cancel.
|
||||
* @{
|
||||
*/
|
||||
EAPI void eina_future_cancel(Eina_Future *f) EINA_ARG_NONNULL(1);
|
||||
|
|
@ -690,7 +693,7 @@ EAPI void eina_future_cancel(Eina_Future *f) EINA_ARG_NONNULL(1);
|
|||
* This function is mainly used by bindings to flush a #Eina_Future_Desc.
|
||||
* It will call the #Eina_Future_Cb with `ENOMEM` and zero the @p desc contents.
|
||||
*
|
||||
* @param desc The #Eina_Future_Desc to flush, if @c NULL this is a noop.
|
||||
* @param[in,out] desc The #Eina_Future_Desc to flush, if @c NULL this is a noop.
|
||||
*/
|
||||
EAPI void eina_future_desc_flush(Eina_Future_Desc *desc);
|
||||
|
||||
|
|
@ -701,7 +704,7 @@ EAPI void eina_future_desc_flush(Eina_Future_Desc *desc);
|
|||
* It will call the #Eina_Future_Error_Cb with `ENOMEM`, the #Eina_Future_Free_Cb and
|
||||
* zero the @p desc contents.
|
||||
*
|
||||
* @param desc The #Eina_Future_Cb_Easy_Desc to flush, if @c NULL this is a noop.
|
||||
* @param[in,out] desc The #Eina_Future_Cb_Easy_Desc to flush, if @c NULL this is a noop.
|
||||
*/
|
||||
EAPI void eina_future_cb_easy_desc_flush(Eina_Future_Cb_Easy_Desc *desc);
|
||||
|
||||
|
|
@ -775,7 +778,9 @@ EAPI void eina_future_cb_easy_desc_flush(Eina_Future_Cb_Easy_Desc *desc);
|
|||
* }
|
||||
* @endcode
|
||||
*
|
||||
* @param[in,out] p The promise obect to create the value from.
|
||||
* @return An Eina_Value. On error the value's type will be @c NULL.
|
||||
*
|
||||
* @note If an error happens the promise will be CANCELED.
|
||||
* @see eina_future_as_value()
|
||||
* @see eina_promise_reject()
|
||||
|
|
@ -789,7 +794,7 @@ EAPI Eina_Value eina_promise_as_value(Eina_Promise *p) EINA_ARG_NONNULL(1) EINA_
|
|||
* This function is used for the same purposes as eina_promise_as_value(),
|
||||
* but receives an Eina_Future instead.
|
||||
*
|
||||
* @param f A future to create a Eina_Value from.
|
||||
* @param[in,out] f A future to create a Eina_Value from.
|
||||
* @return An Eina_Value. On error the value's type will be @c NULL.
|
||||
* @note If an error happens the future @p f will be CANCELED
|
||||
* @see eina_promise_as_value()
|
||||
|
|
@ -811,7 +816,7 @@ EAPI Eina_Value eina_future_as_value(Eina_Future *f)EINA_ARG_NONNULL(1) EINA_WAR
|
|||
* result in an error (@c NULL is returned) and the future
|
||||
* attached to the promise will be canceled!
|
||||
*
|
||||
* @param p A promise used to attach a future. May not be @c NULL.
|
||||
* @param[in,out] p A promise used to attach a future. May not be @c NULL.
|
||||
* @return The future or @c NULL on error.
|
||||
* @note If an error happens this function will CANCEL the promise.
|
||||
* @see eina_promise_new()
|
||||
|
|
@ -835,8 +840,8 @@ EAPI Eina_Future *eina_future_new(Eina_Promise *p) EINA_ARG_NONNULL(1) EINA_WARN
|
|||
* cause the whole chain to be canceled alongside with any pending
|
||||
* promise.
|
||||
*
|
||||
* @param scheduler The scheduler to use.
|
||||
* @param value The value to be delivered. Note that the value
|
||||
* @param[in,out] scheduler The scheduler to use.
|
||||
* @param[in] value The value to be delivered. Note that the value
|
||||
* contents must survive this function scope, that is, do @b not use
|
||||
* stack allocated blobs, arrays, structures or types that keep
|
||||
* references to memory you give. Values will be automatically cleaned
|
||||
|
|
@ -867,8 +872,8 @@ EAPI Eina_Future *eina_future_resolved(Eina_Future_Scheduler *scheduler, Eina_Va
|
|||
* cause the whole chain to be canceled alongside with any pending
|
||||
* promise.
|
||||
*
|
||||
* @param scheduler The scheduler to use.
|
||||
* @param err An Eina_Error value
|
||||
* @param[in,out] scheduler The scheduler to use.
|
||||
* @param[in] err An Eina_Error value
|
||||
*
|
||||
* @return The future or @c NULL on error.
|
||||
*
|
||||
|
|
@ -1015,8 +1020,8 @@ EAPI Eina_Future *eina_future_rejected(Eina_Future_Scheduler *scheduler, Eina_Er
|
|||
* @note This example does manual conversion and print, however we offer
|
||||
* eina_future_cb_convert_to() and eina_future_cb_console_from_desc() and to make those common case easier.
|
||||
*
|
||||
* @param prev A future to link against
|
||||
* @param desc A description struct containing the callback and data.
|
||||
* @param[in,out] prev A future to link against
|
||||
* @param[in] desc A description struct containing the callback and data.
|
||||
* @return A new future or @c NULL on error.
|
||||
* @note If an error happens the whole future chain will CANCELED and
|
||||
* desc.cb will be called in order to free desc.data.
|
||||
|
|
@ -1053,7 +1058,7 @@ EAPI Eina_Future *eina_future_then_from_desc(Eina_Future *prev, const Eina_Futur
|
|||
* @li #Eina_Future_Cb_Log_Desc::line: The __LINE__ macro will be used.
|
||||
*
|
||||
*
|
||||
* @param desc The description data to be used.
|
||||
* @param[in] desc The description data to be used.
|
||||
* @return An #Eina_Future_Desc
|
||||
*
|
||||
* @see #Eina_Future_Cb_Log_Desc
|
||||
|
|
@ -1099,8 +1104,8 @@ EAPI Eina_Future_Desc eina_future_cb_log_from_desc(const Eina_Future_Cb_Log_Desc
|
|||
* }
|
||||
* @endcode
|
||||
*
|
||||
* @param prev The previous future
|
||||
* @param descs An array of descriptions. The last element of the array must have the #Eina_Future_Desc::cb set to @c NULL
|
||||
* @param[in,out] prev The previous future
|
||||
* @param[in] descs An array of descriptions. The last element of the array must have the #Eina_Future_Desc::cb set to @c NULL
|
||||
* @return A future or @c NULL on error.
|
||||
* @note If an error happens the whole future chain will CANCELED and
|
||||
* desc.cb will be called in order to free desc.data.
|
||||
|
|
@ -1127,8 +1132,8 @@ EAPI Eina_Future *eina_future_chain_array(Eina_Future *prev, const Eina_Future_D
|
|||
* check the macro eina_future_chain_easy() for a syntax sugar.
|
||||
*
|
||||
*
|
||||
* @param prev The previous future
|
||||
* @param descs An array of descriptions. The last element of the array must have the #Eina_Future_Desc::cb set to @c NULL
|
||||
* @param[in,out] prev The previous future
|
||||
* @param[in] descs An array of descriptions. The last element of the array must have the #Eina_Future_Desc::cb set to @c NULL
|
||||
* @return A future or @c NULL on error.
|
||||
* @note If an error happens the whole future chain will CANCELED and
|
||||
* desc.cb will be called in order to free desc.data.
|
||||
|
|
@ -1162,11 +1167,14 @@ EAPI Eina_Future *eina_future_chain_easy_array(Eina_Future *prev, const Eina_Fut
|
|||
* eina_future_cb_console("cb2 value:", " cb2 value suffix\n"))
|
||||
* @endcode
|
||||
*
|
||||
* @param prefix A prefix to print, if @c NULL an empty string ("") is used.
|
||||
* @param suffix A suffix to print. If @c NULL '\n' will be used. If suffix is provided
|
||||
* the '\n' must be provided by suffix otherwise the printed text will not contain
|
||||
* a line feed.
|
||||
* @param[in] desc Description object with contextual information.
|
||||
* @return An #Eina_Future_Desc
|
||||
*
|
||||
* The description object, @p desc, can (optionally) include a prefix, suffix,
|
||||
* filename and function name. If these are @c NULL, empty strings ("") are used
|
||||
* instead. If @p desc->suffix is provided, the '\n' should be provided to ensure
|
||||
* the printed string ends with a line feed.
|
||||
*
|
||||
* @see eina_future_then()
|
||||
* @see #Eina_Future_Desc
|
||||
* @see eina_future_chain()
|
||||
|
|
@ -1187,7 +1195,7 @@ EAPI Eina_Future_Desc eina_future_cb_console_from_desc(const Eina_Future_Cb_Cons
|
|||
* specified error happens an EINA_VALUE_EMPTY will be delivered to the
|
||||
* next future in the chain.
|
||||
*
|
||||
* @param err The error to be ignored.
|
||||
* @param[in] err The error to be ignored.
|
||||
* @param A future descriptor to be used with eina_future_then() or eina_future_chain()
|
||||
*/
|
||||
EAPI Eina_Future_Desc eina_future_cb_ignore_error(Eina_Error err);
|
||||
|
|
@ -1195,7 +1203,7 @@ EAPI Eina_Future_Desc eina_future_cb_ignore_error(Eina_Error err);
|
|||
/**
|
||||
* Creates an #Eina_Future_Desc which will convert the the received eina value to a given type.
|
||||
*
|
||||
* @param type The Eina_Value_Type to convert to.
|
||||
* @param[in] type The Eina_Value_Type to convert to.
|
||||
* @return An #Eina_Future_Desc
|
||||
* @see eina_future_then()
|
||||
* @see #Eina_Future_Desc
|
||||
|
|
@ -1274,7 +1282,9 @@ EAPI Eina_Future_Desc eina_future_cb_convert_to(const Eina_Value_Type *type);
|
|||
* }
|
||||
* @endcode
|
||||
*
|
||||
* @param[in] desc The easy callback's description.
|
||||
* @return An #Eina_Future_Desc
|
||||
*
|
||||
* @see eina_future_chain()
|
||||
* @see eina_future_then()
|
||||
* @see eina_future_cb_easy()
|
||||
|
|
@ -1376,7 +1386,7 @@ EAPI Eina_Future_Desc eina_future_cb_easy_from_desc(const Eina_Future_Cb_Easy_De
|
|||
* }
|
||||
* @endcode
|
||||
*
|
||||
* @param array An array of futures, @c #EINA_FUTURE_SENTINEL terminated.
|
||||
* @param[in,out] array An array of futures, @c #EINA_FUTURE_SENTINEL terminated.
|
||||
* @return A promise or @c NULL on error.
|
||||
* @note On error all the futures will be CANCELED.
|
||||
* @see eina_future_all_array()
|
||||
|
|
@ -1488,7 +1498,7 @@ EAPI Eina_Promise *eina_promise_all_array(Eina_Future *array[]) EINA_ARG_NONNULL
|
|||
* }
|
||||
* @endcode
|
||||
*
|
||||
* @param array An array of futures, @c #EINA_FUTURE_SENTINEL terminated.
|
||||
* @param[in,out] array An array of futures, @c #EINA_FUTURE_SENTINEL terminated.
|
||||
* @return A promise or @c NULL on error.
|
||||
* @note On error all the futures will be CANCELED.
|
||||
* @see eina_future_race_array()
|
||||
|
|
@ -1556,7 +1566,7 @@ EAPI extern const Eina_Value_Struct_Desc *EINA_PROMISE_RACE_STRUCT_DESC;
|
|||
* Creates a future that will be resolved once all futures from @p array is resolved.
|
||||
* This is a helper over eina_promise_all_array()
|
||||
*
|
||||
* @param array A future array, must be terminated with #EINA_FUTURE_SENTINEL
|
||||
* @param[in,out] array A future array, must be terminated with #EINA_FUTURE_SENTINEL
|
||||
* @return A future.
|
||||
* @see eina_promise_all_array()
|
||||
* @see #EINA_FUTURE_SENTINEL
|
||||
|
|
@ -1573,7 +1583,7 @@ eina_future_all_array(Eina_Future *array[])
|
|||
* Creates a future that will be resolved once a future @p array is resolved.
|
||||
* This is a helper over eina_promise_race_array()
|
||||
*
|
||||
* @param array A future array, must be terminated with #EINA_FUTURE_SENTINEL
|
||||
* @param[in,out] array A future array, must be terminated with #EINA_FUTURE_SENTINEL
|
||||
* @return A future.
|
||||
* @see eina_promise_race_array()
|
||||
* @see #EINA_FUTURE_SENTINEL
|
||||
|
|
|
|||
Loading…
Reference in New Issue