diff options
author | Lauro Moura <lauromoura@expertisesolutions.com.br> | 2019-03-20 11:26:49 +0100 |
---|---|---|
committer | Xavi Artigas <xavierartigas@yahoo.es> | 2019-03-20 11:35:58 +0100 |
commit | 0860c4f1d7a6fa0f6ecae556cf35d33fa7c13a66 (patch) | |
tree | 6a91520035c9c9ef36673d566565b7e7a63c17de | |
parent | 171467b1fa630853ecf5f59bcc0369f1167865e4 (diff) | |
download | efl-0860c4f1d7a6fa0f6ecae556cf35d33fa7c13a66.tar.gz |
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
-rw-r--r-- | src/bindings/mono/efl_mono/efl_all.cs | 9 | ||||
-rw-r--r-- | src/bindings/mono/efl_mono/efl_csharp_application.cs | 3 | ||||
-rw-r--r-- | src/bindings/mono/eina_mono/eina_accessor.cs | 41 | ||||
-rw-r--r-- | src/bindings/mono/eina_mono/eina_promises.cs | 25 | ||||
-rw-r--r-- | src/bindings/mono/eo_mono/FunctionWrapper.cs | 61 | ||||
-rw-r--r-- | src/bindings/mono/eo_mono/FunctionWrapper_Unix.cs | 9 | ||||
-rw-r--r-- | src/bindings/mono/eo_mono/NativeModule.cs | 5 | ||||
-rw-r--r-- | src/bindings/mono/eo_mono/NativeModule_Unix.cs | 32 | ||||
-rw-r--r-- | src/bindings/mono/meson.build | 1 |
9 files changed, 157 insertions, 29 deletions
diff --git a/src/bindings/mono/efl_mono/efl_all.cs b/src/bindings/mono/efl_mono/efl_all.cs index d8c08d3890..bf78df1d3d 100644 --- a/src/bindings/mono/efl_mono/efl_all.cs +++ b/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; } diff --git a/src/bindings/mono/efl_mono/efl_csharp_application.cs b/src/bindings/mono/efl_mono/efl_csharp_application.cs index b487cf6289..f067b288ec 100644 --- a/src/bindings/mono/efl_mono/efl_csharp_application.cs +++ b/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> diff --git a/src/bindings/mono/eina_mono/eina_accessor.cs b/src/bindings/mono/eina_mono/eina_accessor.cs index c3c09c4966..3f2f71b2b3 100644 --- a/src/bindings/mono/eina_mono/eina_accessor.cs +++ b/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<T>"/>.</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<T>"/>.</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<T>"/>.</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); } diff --git a/src/bindings/mono/eina_mono/eina_promises.cs b/src/bindings/mono/eina_mono/eina_promises.cs index 8be5f9d6cb..176a8835ae 100644 --- a/src/bindings/mono/eina_mono/eina_promises.cs +++ b/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; } diff --git a/src/bindings/mono/eo_mono/FunctionWrapper.cs b/src/bindings/mono/eo_mono/FunctionWrapper.cs index 03e81383bb..5aa4030a2f 100644 --- a/src/bindings/mono/eo_mono/FunctionWrapper.cs +++ b/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> } } - } } diff --git a/src/bindings/mono/eo_mono/FunctionWrapper_Unix.cs b/src/bindings/mono/eo_mono/FunctionWrapper_Unix.cs index 76ee4892ef..845f8239e0 100644 --- a/src/bindings/mono/eo_mono/FunctionWrapper_Unix.cs +++ b/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 } } - } } diff --git a/src/bindings/mono/eo_mono/NativeModule.cs b/src/bindings/mono/eo_mono/NativeModule.cs index 324a933b65..400f24fb87 100644 --- a/src/bindings/mono/eo_mono/NativeModule.cs +++ b/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); diff --git a/src/bindings/mono/eo_mono/NativeModule_Unix.cs b/src/bindings/mono/eo_mono/NativeModule_Unix.cs index 6f6939546c..8783895b14 100644 --- a/src/bindings/mono/eo_mono/NativeModule_Unix.cs +++ b/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}"); diff --git a/src/bindings/mono/meson.build b/src/bindings/mono/meson.build index 3d844e7dac..67c77a647d 100644 --- a/src/bindings/mono/meson.build +++ b/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', |