csharp: Remove missing doc warning by filling them.

Summary:
Added basic documentation for things that were missing.

Some other files are silent due to a pragma disabling CS1591. They
should be handled later.

Also, removed `Efl.Io.Positioner` from the blacklist as it is referenced
from the `Efl.Io.Reader.eos` event documentation.

Reviewers: segfaultxavi

Reviewed By: segfaultxavi

Subscribers: felipealmeida, cedric, #reviewers, #committers

Tags: #efl

Differential Revision: https://phab.enlightenment.org/D8370

src/bindings/mono/efl_mono/efl_all.cs

@@ -36,22 +36,17 @@ static class UnsafeNativeMethods {
     }
 }
 
-public enum Components {
-    Basic,
-    Ui
-}
-
 public static class All {
     private static bool InitializedUi = false;
 
-    public static void Init(Efl.Components components=Components.Basic) {
+    public static void Init(Efl.Csharp.Components components=Efl.Csharp.Components.Basic) {
         Eina.Config.Init();
         Efl.Eo.Config.Init();
         ecore_init();
         evas_init();
         eldbus.Config.Init();
 
-        if (components == Components.Ui) {
+        if (components == Efl.Csharp.Components.Ui) {
             Efl.Ui.Config.Init();
             InitializedUi = true;
         }

src/bindings/mono/efl_mono/efl_csharp_application.cs

@@ -14,8 +14,11 @@ static class UnsafeNativeMethods {
 
 namespace Efl {
   namespace Csharp {
+    ///<summary>The components to be initialized.</summary>
     public enum Components {
+        ///<summary>Basic components: Eina, Eo, Ecore, Evas and DBus.</summary>
         Basic,
+        ///<summary>The same components of <see cref="Efl.Csharp.Components.Basic"/> and the Elementary widget toolkit.</summary>
         Ui,
     }
     /// <summary>

src/bindings/mono/eina_mono/eina_accessor.cs

@@ -27,6 +27,7 @@ public class Accessor<T> : IEnumerable<T>, IDisposable
     private Ownership Ownership { get; set; }
 
     // FIXME Part of the implicit EFL Container interface. Need to make it explicit.
+    ///<summary>Whether this wrapper owns the native accessor.</summary>
     public bool Own
     {
         get
@@ -40,12 +41,18 @@ public class Accessor<T> : IEnumerable<T>, IDisposable
     }
 
     /// <summary>Create a new accessor wrapping the given pointer.</summary>
+    /// <param name="handle">The native handle to be wrapped.</param>
+    /// <param name="owner">Whether this wrapper owns the native accessor.</param>
     public Accessor(IntPtr handle, Ownership owner=Ownership.Managed)
     {
         Handle = handle;
         Ownership = owner;
     }
 
+    /// <summary>Create a new accessor wrapping the given pointer.</summary>
+    /// <param name="handle">The native handle to be wrapped.</param>
+    /// <param name="own">Whether this wrapper owns the native accessor.</param>
+    /// <param name="ownContent">For compatibility with other EFL# containers. Ignored in acessors.</param>
     public Accessor(IntPtr handle, bool own, bool ownContent=false)
         : this(handle, own ? Ownership.Managed : Ownership.Unmanaged)
     {
@@ -57,6 +64,9 @@ public class Accessor<T> : IEnumerable<T>, IDisposable
         Dispose(true);
     }
 
+    /// <summary>Disposes of this wrapper, releasing the native accessor if owned.</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)
     {
         if (Ownership == Ownership.Managed && Handle != IntPtr.Zero)
@@ -66,17 +76,23 @@ public class Accessor<T> : IEnumerable<T>, IDisposable
         }
     }
 
+    /// <summary>Finalizer to be called from the Garbage Collector.</summary>
     ~Accessor()
     {
         Dispose(false);
     }
 
-    public virtual T Convert(IntPtr data)
+    /// <summary>Convert the native data into managed. This is used when returning the data through a
+    /// <see cref="System.Collections.Generic.IEnumerator&lt;T&gt;"/>.</summary>
+    /// <param name="data">The data to be converted</param>
+    /// <returns>The managed data representing <c>data</c>.</returns>
+    protected virtual T Convert(IntPtr data)
     {
         return NativeToManaged<T>(data);
     }
 
     /// <summary>Returns an enumerator that iterates throught this accessor.</summary>
+    /// <returns>An enumerator to walk through the acessor items.</returns>
     public IEnumerator<T> GetEnumerator()
     {
         if (Handle == IntPtr.Zero)
@@ -105,19 +121,38 @@ public class Accessor<T> : IEnumerable<T>, IDisposable
     }
 }
 
+///<summary>Accessor for Inlists.</summary>
 public class AccessorInList<T> : Accessor<T>
 {
+
+    /// <summary>Create a new accessor wrapping the given pointer.</summary>
+    /// <param name="handle">The native handle to be wrapped.</param>
+    /// <param name="own">Whether this wrapper owns the native accessor.</param>
     public AccessorInList(IntPtr handle, Ownership own): base(handle, own) {}
-    public override T Convert(IntPtr data)
+
+    /// <summary>Convert the native data into managed. This is used when returning the data through a
+    /// <see cref="System.Collections.Generic.IEnumerator&lt;T&gt;"/>.</summary>
+    /// <param name="data">The data to be converted</param>
+    /// <returns>The managed data representing <c>data</c>.</returns>
+    protected override T Convert(IntPtr data)
     {
         return NativeToManagedInlistNode<T>(data);
     }
 }
 
+///<summary>Accessor for Inarrays.</summary>
 public class AccessorInArray<T> : Accessor<T>
 {
+    /// <summary>Create a new accessor wrapping the given pointer.</summary>
+    /// <param name="handle">The native handle to be wrapped.</param>
+    /// <param name="own">Whether this wrapper owns the native accessor.</param>
     public AccessorInArray(IntPtr handle, Ownership own): base(handle, own) {}
-    public override T Convert(IntPtr data)
+
+    /// <summary>Convert the native data into managed. This is used when returning the data through a
+    /// <see cref="System.Collections.Generic.IEnumerator&lt;T&gt;"/>.</summary>
+    /// <param name="data">The data to be converted</param>
+    /// <returns>The managed data representing <c>data</c>.</returns>
+    protected override T Convert(IntPtr data)
     {
         return NativeToManagedInplace<T>(data);
     }

src/bindings/mono/eina_mono/eina_promises.cs

@@ -129,6 +129,9 @@ public class Promise : IDisposable
         Dispose(false);
     }
 
+    /// <summary>Disposes of this wrapper, rejecting the native promise with <see cref="Eina.Error.ECANCELED"/></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)
     {
         if (Handle != IntPtr.Zero)
@@ -190,7 +193,7 @@ public class Future
     /// </summary>
     public delegate Eina.Value ResolvedCb(Eina.Value value);
 
-    public IntPtr Handle { get; internal set; }
+    internal IntPtr Handle;
 
     /// <summary>
     /// Creates a Future from a native pointer.
@@ -317,14 +320,23 @@ public class Future
     }
 }
 
+/// <summary>Custom marshaler to convert between managed and native <see cref="Eina.Future"/>.
+/// Internal usage in generated code.</summary>
 public class FutureMarshaler : ICustomMarshaler
 {
 
+    ///<summary>Wrap the native future with a managed wrapper.</summary>
+    ///<param name="pNativeData">Handle to the native future.</param>
+    ///<returns>An <see cref="Eina.Future"/> wrapping the native future.</returns>
     public object MarshalNativeToManaged(IntPtr pNativeData)
     {
         return new Future(pNativeData);
     }
 
+    ///<summary>Extracts the native future from a managed wrapper.</summary>
+    ///<param name="managedObj">The managed wrapper. If it is not an <see cref="Eina.Future"/>, the value returned
+    ///is <see cref="System.IntPtr.Zero"/>.</param>
+    ///<returns>A <see cref="System.IntPtr"/> pointing to the native future.</returns>
     public IntPtr MarshalManagedToNative(object managedObj)
     {
         Future f = managedObj as Future;
@@ -333,20 +345,27 @@ public class FutureMarshaler : ICustomMarshaler
         return f.Handle;
     }
 
+    ///<summary>Not implemented. The code receiving the native data is in charge of releasing it.</summary>
+    ///<param name="pNativeData">The native pointer to be released.</param>
     public void CleanUpNativeData(IntPtr pNativeData) { }
 
+    ///<summary>Not implemented. The runtime takes care of releasing it.</summary>
+    ///<param name="managedObj">The managed object to be cleaned.</param>
     public void CleanUpManagedData(object managedObj) { }
 
+    ///<summary>Size of the native data size returned</summary>
+    ///<returns>The size of the data.</returns>
     public int GetNativeDataSize()
     {
         return -1;
     }
 
+    ///<summary>Gets an instance of this marshaller.</summary>
+    ///<param name="cookie">A name that could be used to customize the returned marshaller. Currently not used.</param>
+    ///<returns>The <see cref="Eina.FutureMarshaler"/> instance that will marshall the data.</returns>
     public static ICustomMarshaler GetInstance(string cookie) {
         if (marshaler == null)
-        {
             marshaler = new FutureMarshaler();
-        }
         return marshaler;
     }
 

src/bindings/mono/eo_mono/FunctionWrapper.cs

@@ -3,8 +3,17 @@ using System.Runtime.InteropServices;
 
 namespace Efl { namespace Eo {
 
+///<summary>Class to load functions pointers from a native module.
+///
+///This class has a platform-dependent implementation on whether it
+///is compiled for Windows (using LoadLibrary/GetProcAddress) or Unix
+///(dlopen/dlsym).</summary>
 public partial class FunctionInterop
 {
+    ///<summary>Loads a function pointer from the given module.</summary>
+    ///<param name="moduleName">The name of the module containing the function.</param>
+    ///<param name="functionName">The name of the function to search for.</param>
+    ///<returns>A function pointer that can be used with delegates.</returns>
     public static IntPtr LoadFunctionPointer(string moduleName, string functionName)
     {
         NativeModule module = new NativeModule(moduleName);
@@ -13,6 +22,10 @@ public partial class FunctionInterop
         Eina.Log.Debug($"searching {module.Module} for{functionName}, result {s}");
         return s;
     }
+
+    ///<summary>Loads a function pointer from the default module.</summary>
+    ///<param name="functionName">The name of the function to search for.</param>
+    ///<returns>A function pointer that can be used with delegates.</returns>
     public static IntPtr LoadFunctionPointer(string functionName)
     {
         Eina.Log.Debug($"searching {null} for {functionName}");
@@ -21,8 +34,14 @@ public partial class FunctionInterop
         return s;
     }
 }
-        
+
-public class FunctionWrapper<T>
+///<summary>Wraps a native function in a portable manner.
+///
+///This is intended as a workaround DllImport limitations when switching between mono and dotnet.
+///
+///The parameter T must be a delegate.
+///</summary>
+public class FunctionWrapper<T> // NOTE: When supporting C# >=7.3, add a where T: System.Delegate?
 {
     private Lazy<FunctionLoadResult<T>> loadResult;
 #pragma warning disable 0414
@@ -42,12 +61,18 @@ public class FunctionWrapper<T>
                 return new FunctionLoadResult<T>(Marshal.GetDelegateForFunctionPointer<T>(funcptr));
         }
     }
-    
+
+    ///<summary>Creates a wrapper for the given function of the given module.</summary>
+    ///<param name="moduleName">The name of the module containing the function.</param>
+    ///<param name="functionName">The name of the function to search for.</param>
     public FunctionWrapper(string moduleName, string functionName)
         : this (new NativeModule(moduleName), functionName)
     {
     }
-    
+
+    ///<summary>Creates a wrapper for the given function of the given module.</summary>
+    ///<param name="module">The module wrapper containing the function.</param>
+    ///<param name="functionName">The name of the function to search for.</param>
     public FunctionWrapper(NativeModule module, string functionName)
     {
         this.module = module;
@@ -58,6 +83,8 @@ public class FunctionWrapper<T>
             });
     }
 
+    ///<summary>Retrieves the result of function load.</summary>
+    ///<returns>The load result.</returns>
     public FunctionLoadResult<T> Value
     {
         get
@@ -67,12 +94,26 @@ public class FunctionWrapper<T>
     }
 }
 
-public enum FunctionLoadResultKind { Success, LibraryNotFound, FunctionNotFound }
+///<summary>The outcome of the function load process.</summary>
-    
+public enum FunctionLoadResultKind {
+    ///<summary>Function was loaded successfully.</summary>
+    Success,
+    ///<summary>Library was not found.</summary>
+    LibraryNotFound,
+    ///<summary>Function symbol was not found in the given module.</summary>
+    FunctionNotFound
+}
+
+///<summary>Represents the result of loading a function pointer.</summary>
 public class FunctionLoadResult<T>
 {
+    ///<summary>The status of the load.</summary>
     public FunctionLoadResultKind Kind;
-    public T _Delegate;
+    private T _Delegate;
+
+    ///<summary>The delegate wrapping the loaded function pointer.
+    ///
+    ///Throws InvalidOperationException if trying to access while not loaded.</summary>
     public T Delegate
     {
         get {
@@ -82,10 +123,15 @@ public class FunctionLoadResult<T>
         }
     }
 
+    ///<summary>Creates a new load result of the given kind.</summary>
+    ///<param name="kind">The outcome of the load process.</param>
     public FunctionLoadResult(FunctionLoadResultKind kind)
     {
         this.Kind = kind;
     }
+
+    ///<summary>Creates a new load result with the given delegate.</summary>
+    ///<param name="Delegate">The delegate wrapping the native function.</param>
     public FunctionLoadResult(T Delegate)
     {
         this._Delegate = Delegate;
@@ -93,5 +139,4 @@ public class FunctionLoadResult<T>
     }
 }
 
-
 } }

src/bindings/mono/eo_mono/FunctionWrapper_Unix.cs

@@ -6,8 +6,12 @@ namespace Efl { namespace Eo {
 public partial class FunctionInterop
 {
     [DllImport(efl.Libs.Libdl)]
-    public static extern IntPtr dlsym(IntPtr handle, string symbol);
+    private static extern IntPtr dlsym(IntPtr handle, string symbol);
-        
+
+    ///<summary>Loads a function pointer from the given module.</summary>
+    ///<param name="nativeLibraryHandle">The module containing the function.</param>
+    ///<param name="functionName">The name of the function to search for.</param>
+    ///<returns>A function pointer that can be used with delegates.</returns>
     public static IntPtr LoadFunctionPointer(IntPtr nativeLibraryHandle, string functionName)
     {
         Eina.Log.Debug("searching {nativeLibraryHandle} for {functionName}");
@@ -17,5 +21,4 @@ public partial class FunctionInterop
     }
 }
 
-
 } }

src/bindings/mono/eo_mono/NativeModule.cs

@@ -2,10 +2,13 @@ using System;
 
 namespace Efl { namespace Eo {
 
+///<summary>Wraps a native module that was opened with dlopen/LoadLibrary.</summary>
 public partial class NativeModule : IDisposable
 {
     private Lazy<IntPtr> module;
 
+    ///<summary>Lazily tries to load the module with the given name.</summary>
+    ///<param name="libName">The name of the module to load.</param>
     public NativeModule(string libName)
     {
         module = new Lazy<IntPtr>
@@ -15,6 +18,7 @@ public partial class NativeModule : IDisposable
              });
     }
 
+    ///<summary>The module that was loaded.</summary>
     public IntPtr Module
     {
         get
@@ -23,6 +27,7 @@ public partial class NativeModule : IDisposable
         }
     }
 
+    ///<summary>Unload and released the handle to the wrapped module.</summary>
     public void Dispose()
     {
         UnloadLibrary(module.Value);

src/bindings/mono/eo_mono/NativeModule_Unix.cs

@@ -5,21 +5,45 @@ namespace Efl { namespace Eo {
 
 public partial class NativeModule
 {
-    public const int RTLD_NOW = 0x002;
+    private const int RTLD_NOW = 0x002;
     // Currently we are using GLOBAL due to issues
     // with the way evas modules are built.
-    public const int RTLD_GLOBAL = 0x100;
+    private const int RTLD_GLOBAL = 0x100;
 
     [DllImport(efl.Libs.Libdl)]
-    public static extern IntPtr dlopen(string fileName, int flag);
+    private static extern IntPtr dlopen(string fileName, int flag);
     [DllImport(efl.Libs.Libdl)]
-    public static extern int dlclose(IntPtr handle);
+    private static extern int dlclose(IntPtr handle);
 
+    ///<summary>Closes the library handle.</summary>
+    ///<param name="handle">The handle to the library.</param>
     public static void UnloadLibrary(IntPtr handle)
     {
         dlclose(handle);
     }
 
+    ///<summary>Loads the given library.
+    ///
+    ///It attempts to load using the following list of names based on the <c>filename</c>
+    ///parameter:
+    ///
+    ///<list type="bullet">
+    ///<item>
+    ///<description><c>filename</c></description>
+    ///</item>
+    ///<item>
+    ///<description><c>libfilename</c></description>
+    ///</item>
+    ///<item>
+    ///<description><c>filename.so</c></description>
+    ///</item>
+    ///<item>
+    ///<description><c>libfilename.so</c></description>
+    ///</item>
+    ///</list>
+    ///</summary>
+    ///<param name="filename">The name to search for.</param>
+    ///<returns>The loaded library handle or <see cref="System.IntPtr.Zero"/> on failure.</returns>
     public static IntPtr LoadLibrary(string filename)
     {
         Eina.Log.Debug($"Loading library {filename}");

src/bindings/mono/meson.build

@@ -62,7 +62,6 @@ blacklisted_files = [
   'efl_vg_root_node.eo',
   'efl_vg_shape.eo.cs',
   'efl_io_buffer.eo',
-  'efl_io_positioner.eo',
   'efl_io_queue.eo',
   'efl_io_sizer.eo',
   'efl_io_closer_fd.eo',