From ec501a6623e8132caea14ad7e382d6e7c2f348c0 Mon Sep 17 00:00:00 2001 From: Vitor Sousa Date: Mon, 8 Jul 2019 17:18:47 +0200 Subject: [PATCH] csharp: fix some build warnings related with incorrect and missing documentation Summary: Some parameter names, tag names and cref identifiers in the documentation were incorrect and causing warnings during compilation. There were also warnings related with missing documentation in publicly visible elements in the manual binding. This commit fixes these incorrections and adds documentation to the manual binding in order to solve these compilation warnings. Warnings related with missing documentation in `.eo` files are still present. Test Plan: Just compile with mono binding. Reviewers: lauromoura, felipealmeida, segfaultxavi Reviewed By: segfaultxavi Subscribers: cedric, #reviewers, #committers Tags: #efl Differential Revision: https://phab.enlightenment.org/D9243 --- src/bin/eolian_mono/eolian/mono/klass.hh | 3 +- .../mono/eina_mono/eina_stringshare.cs | 68 +++++++++---------- src/bindings/mono/eo_mono/EoWrapper.cs | 30 +++++++- src/bindings/mono/eo_mono/iwrapper.cs | 4 +- 4 files changed, 66 insertions(+), 39 deletions(-) diff --git a/src/bin/eolian_mono/eolian/mono/klass.hh b/src/bin/eolian_mono/eolian/mono/klass.hh index 8f9932664b..c34d7c06e0 100644 --- a/src/bin/eolian_mono/eolian/mono/klass.hh +++ b/src/bin/eolian_mono/eolian/mono/klass.hh @@ -214,6 +214,7 @@ struct klass << scope_tab << scope_tab << name_helpers::klass_get_name(cls) << "();\n" << scope_tab << "/// Initializes a new instance of the class.\n" << scope_tab << "/// Internal usage: This is used when interacting with C code and should not be used directly.\n" + << scope_tab << "/// The native pointer to be wrapped.\n" << scope_tab << "private " << concrete_name << "(Efl.Eo.Globals.WrappingHandle wh) : base(wh)\n" << scope_tab << "{\n" << scope_tab << "}\n\n" @@ -510,7 +511,7 @@ struct klass << scope_tab << "}\n\n" << scope_tab << "/// Initializes a new instance of the class.\n" << scope_tab << "/// Internal usage: Constructs an instance from a native pointer. This is used when interacting with C code and should not be used directly.\n" - << scope_tab << "/// The native pointer to be wrapped.\n" + << scope_tab << "/// The native pointer to be wrapped.\n" << scope_tab << "protected " << inherit_name << "(Efl.Eo.Globals.WrappingHandle wh) : base(wh)\n" << scope_tab << "{\n" << scope_tab << "}\n\n" diff --git a/src/bindings/mono/eina_mono/eina_stringshare.cs b/src/bindings/mono/eina_mono/eina_stringshare.cs index 087db51bce..5b97e731e4 100644 --- a/src/bindings/mono/eina_mono/eina_stringshare.cs +++ b/src/bindings/mono/eina_mono/eina_stringshare.cs @@ -47,29 +47,29 @@ public static partial class NativeMethods /// public class Stringshare : IEquatable, IEquatable { - /// + /// /// Main constructor. Wrap the given string. /// Have private acess to avoid wrapping a null reference, /// use convertion or the factory method to create a new instance. - /// - /// - /// + /// + /// + /// private Stringshare(string s) { Str = s; } - /// + /// /// Auto-implemented property that holds the wrapped string value. - /// + /// public string Str { get; private set; } - /// + /// /// Factory method to instantiate a new object. /// Get a wrappper for the given string or a null reference if the given /// string reference is also null. - /// - /// + /// + /// /// /// A new instance wrapping the given string, or a null reference if /// the given string reference is also null. @@ -84,9 +84,9 @@ public class Stringshare : IEquatable, IEquatable return new Stringshare(s); } - /// + /// /// Implicit convertion to string. - /// + /// public static implicit operator string(Stringshare ss) { if (ReferenceEquals(null, ss)) @@ -97,13 +97,13 @@ public class Stringshare : IEquatable, IEquatable return ss.Str; } - /// + /// /// Implicit convertion from string to Stringshare. - /// + /// /// /// Note that this method can be used to create an instance of this class, /// either via an explicit cast or an implicit convertion. - /// + /// /// public static implicit operator Stringshare(string s) { @@ -115,9 +115,9 @@ public class Stringshare : IEquatable, IEquatable return new Stringshare(s); } - /// + /// /// Check two Stringshare objects for equality. - /// + /// /// /// True if both wrapped strings have the same content or if both /// references are null, false otherwise. @@ -128,9 +128,9 @@ public class Stringshare : IEquatable, IEquatable } - /// + /// /// Check two Stringshare objects for inequality. - /// + /// /// /// True if the wrapped strings have different content or if one reference is null /// and the other is not, false otherwise. @@ -140,20 +140,20 @@ public class Stringshare : IEquatable, IEquatable return !(ss1 == ss2); } - /// + /// /// Returns the wrapped string. - /// - /// - /// + /// + /// + /// /// The wrapped string. Same as the property Str. public override string ToString() { return Str; } - /// + /// /// Override of GetHashCode for consistency with user-defined equality methods. - /// + /// /// /// The wrapped string hash code. /// @@ -162,9 +162,9 @@ public class Stringshare : IEquatable, IEquatable return Str.GetHashCode(); } - /// + /// /// Check the given object for equality. - /// + /// /// /// True if the given object is the same object or if it is another Stringshare object /// and both wrapped strings are equal or if it is a string object and its content @@ -191,9 +191,9 @@ public class Stringshare : IEquatable, IEquatable return other.GetType() == typeof(Stringshare) && this == ((Stringshare)other); } - /// + /// /// Check the given Stringshare for equality. - /// + /// /// /// True if the given Stringshare object is not null and its wrapped string /// have the same content of this.Str, false otherwise. @@ -203,9 +203,9 @@ public class Stringshare : IEquatable, IEquatable return this == other; } - /// + /// /// Check the given Stringshare for equality. - /// + /// /// /// True if the given string is not null and the wrapped string have the same /// content of the given string, false otherwise. @@ -215,11 +215,11 @@ public class Stringshare : IEquatable, IEquatable return this.Str == other; } - /// + /// /// Get the wrapped string. - /// - /// - /// + /// + /// + /// /// The wrapped string. Same as the property Str. public string Get() { diff --git a/src/bindings/mono/eo_mono/EoWrapper.cs b/src/bindings/mono/eo_mono/EoWrapper.cs index 5b14b48695..03edea018c 100644 --- a/src/bindings/mono/eo_mono/EoWrapper.cs +++ b/src/bindings/mono/eo_mono/EoWrapper.cs @@ -10,8 +10,15 @@ namespace Efl namespace Eo { +/// +/// Abstract class that delivers base level binding to Efl Objects. +/// +/// Most of it is protected functionalities to serve the generated +/// binding classes that inherit from it. +/// public abstract class EoWrapper : IWrapper, IDisposable { + /// Object used to synchronize access to EFL events. protected readonly object eflBindingEventLock = new object(); private bool generated = true; private System.IntPtr handle = IntPtr.Zero; @@ -49,7 +56,7 @@ public abstract class EoWrapper : IWrapper, IDisposable /// Initializes a new instance of the class. /// Internal usage: Constructs an instance from a native pointer. This is used when interacting with C code and should not be used directly. /// Do not implement this constructor. - /// The native pointer to be wrapped. + /// The native pointer to be wrapped. protected EoWrapper(Efl.Eo.Globals.WrappingHandle wh) { handle = wh.NativeHandle; @@ -124,6 +131,15 @@ public abstract class EoWrapper : IWrapper, IDisposable get; } + /// + /// Whether this object type is one of the generated binding classes or a custom + /// class defined by the user and that inherit from one of the generated ones. + /// + /// + /// True if this object type is one of the generated binding classes, + /// false if it is class that is manually defined and that inherits from + /// one of the generated ones, including user defined classes. + /// protected bool IsGeneratedBindingClass { get { return generated; } @@ -269,7 +285,7 @@ public abstract class EoWrapper : IWrapper, IDisposable ws.MakeShared(); } - /// Create and set to the internal native state a C# supervisor for this Eo wrapper. For internal use only. + /// Create and set to the internal native state a C# supervisor for this Eo wrapper. For internal use only. private void AddWrapperSupervisor() { var ws = new Efl.Eo.WrapperSupervisor(this); @@ -291,16 +307,24 @@ public abstract class EoWrapper : IWrapper, IDisposable Eina.Error.RaiseIfUnhandledException(); } + /// + /// Struct to be used when constructing objects from native code. + /// Wraps the pointer handle to the native object instance. + /// protected struct ConstructingHandle { + /// Constructor for wrapping the native handle. public ConstructingHandle(IntPtr h) { NativeHandle = h; } + /// Pointer to the native instance. public IntPtr NativeHandle { get; private set; } } + /// Wrapper for native methods and virtual method delegates. + /// For internal use by generated code only. public abstract class NativeMethods : Efl.Eo.NativeClass { private static EflConstructorDelegate csharpEflConstructorStaticDelegate = new EflConstructorDelegate(Constructor); @@ -308,6 +332,8 @@ public abstract class EoWrapper : IWrapper, IDisposable private delegate IntPtr EflConstructorDelegate(IntPtr obj, IntPtr pd); + /// Gets the list of Eo operations to override. + /// The list of Eo operations to be overload. public override System.Collections.Generic.List GetEoOps(Type type) { var descs = new System.Collections.Generic.List(); diff --git a/src/bindings/mono/eo_mono/iwrapper.cs b/src/bindings/mono/eo_mono/iwrapper.cs index 7c2eeb452b..833ae78302 100644 --- a/src/bindings/mono/eo_mono/iwrapper.cs +++ b/src/bindings/mono/eo_mono/iwrapper.cs @@ -716,11 +716,11 @@ public class Globals Monitor.Exit(Efl.All.InitLock); } - /// + /// /// Internal struct used by the binding to pass the native handle pointer /// to the managed object wrapping constructor. /// Internal usage only: do not use this class in inherited classes. - /// + /// public struct WrappingHandle { public WrappingHandle(IntPtr h)