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

diff --git a/src/bindings/mono/eina_mono/eina_promises.cs b/src/bindings/mono/eina_mono/eina_promises.cs
index 897d200..a2cef0d 100644 (file)
--- 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
 {