csharp: Add some docs to MVVM infrastructure

Reviewers: SanghyeonLee, felipealmeida, cedric, segfaultxavi

Reviewed By: segfaultxavi

Subscribers: #reviewers, #committers

Tags: #efl

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

diff --git a/src/bindings/mono/efl_mono/GenericModel.cs b/src/bindings/mono/efl_mono/GenericModel.cs
index 79cca5f..b9ef325 100644 (file)
--- a/src/bindings/mono/efl_mono/GenericModel.cs
+++ b/src/bindings/mono/efl_mono/GenericModel.cs
@@ -9,10 +9,17 @@ using Eina;
 
 namespace Efl {
 
-/// <summary>Generic <see cref="Efl.IModel" /> implementation for MVVM models based on <see cref="Efl.UserModel&lt;T&gt;" />
+/// <summary>
+/// Generic <see cref="Efl.IModel" /> helper class to ease manual implementation of C# models.
 ///
-/// Since EFL 1.23.
+/// <para>It provides an expanded API like async helpers to get children.</para>
+///
+/// <para>For MVVM-based models, <see cref="Efl.UserModel&lt;T&gt;" /> provides a simpler API.</para>
+///
+/// <para>Since EFL 1.24.</para>
 /// </summary>
+/// <typeparam name="T">The type of the child model. It is the type used when adding/removing/getting items to this
+/// model.</typeparam>
 public class GenericModel<T> : Efl.Object, Efl.IModel, IDisposable
 {
    private Efl.IModel model;
@@ -78,7 +85,7 @@ public class GenericModel<T> : Efl.Object, Efl.IModel, IDisposable
       ModelHelper.SetProperties(o, child);
    }
 
-   /// <summary>Adds a new childs to the model and returns it.</summary>
+   /// <summary>Adds a new child to the model and returns it.</summary>
    public Efl.Object AddChild()
    {
        return model.AddChild();

diff --git a/src/bindings/mono/efl_mono/UserModel.cs b/src/bindings/mono/efl_mono/UserModel.cs
index 08e6f6e..c2597cc 100644 (file)
--- a/src/bindings/mono/efl_mono/UserModel.cs
+++ b/src/bindings/mono/efl_mono/UserModel.cs
@@ -49,8 +49,8 @@ internal class ModelHelper
 
 /// <summary>Helper class to simplify the creation of MVVM Models based on <see cref="Efl.IModel" />.
 ///
-/// <para>This class works together with <see cref="Efl.GenericModel&lt;T&gt;" /> to wrap user defined classes as MVVM models.
-/// Example:</para>
+/// <para>This class enables usage of simple model classes to define the data to be stored in the native model
+/// and presented in a friendly manner to the C# developer. Example:</para>
 ///
 /// <code>
 /// public class PersonModel
@@ -65,12 +65,18 @@ internal class ModelHelper
 /// PersonModel p = await model.GetAtAsync(0);
 /// </code>
 ///
-/// Since EFL 1.23.
+/// <para>Since EFL 1.24.</para>
 /// </summary>
+/// <typeparam name="T">The enclosed C# model class with the properties to be added to the native model.</typeparam>
 [Efl.Eo.BindingEntity]
 public class UserModel<T> : Efl.MonoModelInternal, IDisposable
 {
-   /// <summary>Creates a new model.</summary>
+   /// <summary>
+   /// Creates a new root model.
+   ///
+   /// <para>The properties of <code>T</code> will be added to the underlying native model as properties the user can get/set on children
+   /// of this model.</para>
+   /// </summary>
    /// <param name="parent">The parent of the model.</param>
    public UserModel (Efl.Object parent = null) : base(Efl.MonoModelInternal.efl_mono_model_internal_class_get(), parent)
    {
@@ -87,9 +93,9 @@ public class UserModel<T> : Efl.MonoModelInternal, IDisposable
        Dispose(false);
    }
 
-   /// <summary>Adds a new child to the model wrapping the properites of <c>o</c>
+   /// <summary>Adds a new child to the model wrapping the properties of <c>o</c>
    ///
-   /// <para>Reflection is used to instantiate a new <see cref="Efl.IModel" /> for this child and
+   /// <para>Reflection is used to instantiate a new <see cref="Efl.IModel" />-based class for this child and
    /// set the mirroring properties correctly.</para>
    /// </summary>
    ///

diff --git a/src/lib/efl_mono/efl_mono_model_internal.eo b/src/lib/efl_mono/efl_mono_model_internal.eo
index 3a639de..71b3313 100644 (file)
--- a/src/lib/efl_mono/efl_mono_model_internal.eo
+++ b/src/lib/efl_mono/efl_mono_model_internal.eo
@@ -1,10 +1,18 @@
 class @beta Efl.Mono_Model_Internal extends Efl.Loop_Consumer implements Efl.Model
 {
+  [[Internal @Efl.Model implementation for the root models in C# MVVM infrastructure.
+
+    This represents the root model, containing @Efl.Mono_Model_Internal_Child elements. It is inherited from classes
+    like the C#-only Efl.UserModel<T>, which the end user will actually instantiate.
+  ]]
   methods {
     add_property {
+      [[Adds a new property to the wrapped children models.
+
+        When adding new children models, these children will have the properties that were added from this method.]]
       params {
-        @in name: string;
-        @in type: ptr(const(Eina.Value_Type));
+        @in name: string; [[Name of the property being added.]]
+        @in type: ptr(const(Eina.Value_Type)); [[Type of the property being added, as an @Eina.Value_Type.]]
       }
     }
   }

diff --git a/src/lib/efl_mono/efl_mono_model_internal_child.eo b/src/lib/efl_mono/efl_mono_model_internal_child.eo
index eebb797..b8bf3ac 100644 (file)
--- a/src/lib/efl_mono/efl_mono_model_internal_child.eo
+++ b/src/lib/efl_mono/efl_mono_model_internal_child.eo
@@ -1,5 +1,9 @@
 class @beta Efl.Mono_Model_Internal_Child extends Efl.Loop_Consumer implements Efl.Model
 {
+  [[Internal @Efl.Model implementation for the actual model data contained in a root @Efl.Mono_Model_Internal.
+
+    This model's properties are added through C# reflection on the user-provided model through Efl.GenericModel<T>.
+  ]]
   implements {
     Efl.Object.constructor;
     Efl.Object.destructor;