lauromoura pushed a commit to branch master. http://git.enlightenment.org/core/efl.git/commit/?id=64e22aaadad980d65e2bb2531374b399f0c876f8
commit 64e22aaadad980d65e2bb2531374b399f0c876f8 Author: Lauro Moura <[email protected]> Date: Tue Oct 15 10:10:53 2019 -0300 csharp: Fix promises docs and hide api Summary: ref T8293 Reviewers: felipealmeida, brunobelo, segfaultxavi, woohyun Reviewed By: brunobelo Subscribers: cedric, #reviewers, #committers Tags: #efl Maniphest Tasks: T8293 Differential Revision: https://phab.enlightenment.org/D10331 --- src/bindings/mono/eina_mono/eina_promises.cs | 69 ++++++++++++++++++++-------- 1 file changed, 49 insertions(+), 20 deletions(-) diff --git a/src/bindings/mono/eina_mono/eina_promises.cs b/src/bindings/mono/eina_mono/eina_promises.cs index 897d200cf1..a2cef0d15c 100644 --- a/src/bindings/mono/eina_mono/eina_promises.cs +++ b/src/bindings/mono/eina_mono/eina_promises.cs @@ -2,6 +2,7 @@ using System; using System.Runtime.InteropServices; using System.Collections.Generic; using System.Linq; +using System.ComponentModel; using static Eina.EinaNative.PromiseNativeMethods; @@ -12,6 +13,7 @@ namespace Eina namespace EinaNative { +[EditorBrowsable(EditorBrowsableState.Never)] static internal class PromiseNativeMethods { internal delegate void Promise_Cancel_Cb(IntPtr data, IntPtr dead); @@ -71,14 +73,16 @@ static internal class PromiseNativeMethods /// /// With a Promise you can attach futures to it, which will be used to notify of the value being available. /// -/// Since Efl 1.23. +/// <para>Since Efl 1.23.</para> /// </summary> public class Promise : IDisposable { internal IntPtr Handle; private GCHandle CleanupHandle; - /// <summary>Delegate for functions that will be called upon a promise cancellation.</summary> + /// <summary>Delegate for functions that will be called upon a promise cancellation. + /// <para>Since EFL 1.23.</para> + /// </summary> public delegate void CancelCb(); /// <summary> @@ -86,6 +90,7 @@ public class Promise : IDisposable /// /// Currently, creating a promise directly uses the Main Loop scheduler the source of notifications (i.e. the /// future callbacks will be called mainly from a loop iteration). + /// <para>Since EFL 1.23.</para> /// </summary> public Promise(CancelCb cancelCb = null) { @@ -133,20 +138,26 @@ public class Promise : IDisposable handle.Free(); } - /// <summary>Dispose this promise, causing its cancellation if it isn't already fulfilled.</summary> + /// <summary>Dispose this promise, causing its cancellation if it isn't already fulfilled. + /// <para>Since EFL 1.23.</para> + /// </summary> public void Dispose() { Dispose(true); GC.SuppressFinalize(this); } - /// <summary>Finalizer to be called from the Garbage Collector.</summary> + /// <summary>Finalizer to be called from the Garbage Collector. + /// <para>Since EFL 1.23.</para> + /// </summary> ~Promise() { Dispose(false); } - /// <summary>Disposes of this wrapper, rejecting the native promise with <see cref="Eina.Error.ECANCELED"/></summary> + /// <summary>Disposes of this wrapper, rejecting the native promise with <see cref="Eina.Error.ECANCELED"/>. + /// <para>Since EFL 1.23.</para> + /// </summary> /// <param name="disposing">True if this was called from <see cref="Dispose()"/> public method. False if /// called from the C# finalizer.</param> protected virtual void Dispose(bool disposing) @@ -176,7 +187,8 @@ public class Promise : IDisposable /// <summary> /// Fulfills a promise with the given value. /// - /// This will make all futures attached to it to be called with the given value as payload. + /// <para>This will make all futures attached to it to be called with the given value as payload.</para> + /// <para>Since EFL 1.23.</para> /// </summary> public void Resolve(Eina.Value value) { @@ -193,8 +205,9 @@ public class Promise : IDisposable /// <summary> /// Rejects a promise. /// - /// The future chain attached to this promise will be called with an Eina.Value of type - /// Eina.ValueType.Error and payload Eina.Error.ECANCELED. + /// <para>The future chain attached to this promise will be called with an Eina.Value of type + /// <see cref="Eina.ValueType.Error" /> and payload <see cref="Eina.Error.ECANCELED" />.</para> + /// <para>Since EFL 1.23.</para> /// </summary> public void Reject(Eina.Error reason) { @@ -207,17 +220,19 @@ public class Promise : IDisposable /// <summary> /// Futures are the structures holding the callbacks to be notified of a promise fullfillment /// or cancellation. +/// <para>Since EFL 1.23.</para> /// </summary> public class Future { /// <summary> /// Callback attached to a future and to be called when resolving/rejecting a promise. /// - /// The Eina.Value as argument can come with an Eina.Error.ECANCELED as payload if the - /// promise/future was rejected/cancelled. + /// <para>The Eina.Value as argument can come with an <see cref="Eina.Error.ECANCELED" /> as payload if the + /// promise/future was rejected/cancelled.</para> /// - /// The return value usually is same as the argument, forwarded, but can be changed in - /// case were the chain act as a transforming pipeline. + /// <para>The return value usually is same as the argument, forwarded, but can be changed in + /// case were the chain act as a transforming pipeline.</para> + /// <para>Since EFL 1.23.</para> /// </summary> public delegate Eina.Value ResolvedCb(Eina.Value value); @@ -225,7 +240,9 @@ public class Future /// <summary> /// Creates a Future from a native pointer. + /// <para>Since EFL 1.23.</para> /// </summary> + [EditorBrowsable(EditorBrowsableState.Never)] public Future(IntPtr handle) { handle = ThenRaw(handle, (Eina.Value value) => @@ -239,9 +256,13 @@ public class Future /// <summary> /// Creates a Future attached to the given Promise. /// - /// Optionally a resolved callback may be provided. If so, it will be chained - /// before the returned future. + /// <para>Optionally a resolved callback may be provided. If so, it will be chained + /// before the returned future.</para> + /// <para>Since EFL 1.23.</para> /// </summary> + /// <param name="promise">The <see cref="Eina.Promise" /> which rejection or resolution will cause + /// the future to trigger.</param> + /// <param name="cb">The callback to be called when the attached promise resolves.</param> public Future(Promise promise, ResolvedCb cb = null) { IntPtr intermediate = eina_future_new(promise.Handle); @@ -268,8 +289,9 @@ public class Future /// <summary> /// Cancels this future and the chain it belongs to, along with the promise linked against it. /// - /// The callbacks will still be called with Eina.Error.ECANCELED as payload. The promise cancellation - /// callback will also be called if present. + /// <para>The callbacks will still be called with <see cref="Eina.Error.ECANCELED" /> as payload. The promise cancellation + /// callback will also be called if present.</para> + /// <para>Since EFL 1.23.</para> /// </summary> public void Cancel() { @@ -280,12 +302,15 @@ public class Future /// <summary> /// Creates a new future to be called after this one. /// - /// Once the promise this future is attached to resolves, the callbacks on the chain - /// are called in the order they were chained. + /// <para>Once the promise this future is attached to resolves, the callbacks on the chain + /// are called in the order they were chained.</para> /// - /// CAUTION: Calling Then() on a future that had it called before will replace the previous chain - /// from this point on. + /// <para>CAUTION: Calling Then() on a future that had it called before will replace the previous chain + /// from this point on.</para> + /// <para>Since EFL 1.23.</para> /// </summary> + /// <param name="cb">The callback to be called when this future is resolved.</param> + /// <returns>A new future in the chain after registering the callback.</returns> public Future Then(ResolvedCb cb) { SanityChecks(); @@ -332,7 +357,10 @@ public class Future /// /// It is just syntatic sugar for sequential Then() calls, without creating intermediate /// futures explicitly. + /// <para>Since EFL 1.23.</para> /// </summary> + /// <param name="cbs">An enumerable with the callbacks to be chained together.</param> + /// <returns>The future representing the chain.</returns> public Future Chain(IEnumerable<ResolvedCb> cbs) { SanityChecks(); @@ -375,6 +403,7 @@ public class Future /// <summary>Custom marshaler to convert between managed and native <see cref="Eina.Future"/>. /// Internal usage in generated code.</summary> +[EditorBrowsable(EditorBrowsableState.Never)] public class FutureMarshaler : ICustomMarshaler { --
