csharp: Document Eina.List

Summary:
Also added Since 1.23 info

Depends on D10253o

ref T8293

Test Plan: Check docs

Reviewers: segfaultxavi, brunobelo, felipealmeida

Reviewed By: felipealmeida

Subscribers: cedric, #reviewers, #committers

Tags: #efl

Maniphest Tasks: T8293

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

src/bindings/mono/eina_mono/eina_list.cs

@@ -3,6 +3,7 @@
 using System;
 using System.Runtime.InteropServices;
 using System.Collections.Generic;
+using System.ComponentModel;
 
 using static Eina.TraitFunctions;
 using static Eina.ListNativeFunctions;
@@ -11,6 +12,7 @@ using Eina.Callbacks;
 namespace Eina
 {
 
+[EditorBrowsable(EditorBrowsableState.Never)]
 public static class ListNativeFunctions
 {
     [DllImport(efl.Libs.Eina)] public static extern IntPtr
@@ -104,16 +106,22 @@ public static class ListNativeFunctions
         eina_list_last_data_get_custom_export_mono(IntPtr list);
 }
 
+/// <summary>Native wrapper around a linked list of items. (Since EFL 1.23)</summary>
 public class List<T> : IEnumerable<T>, IDisposable
 {
+
+    [EditorBrowsable(EditorBrowsableState.Never)]
     public IntPtr Handle {get;set;} = IntPtr.Zero;
+    /// <summary>Whether this managed list owns the native one.</summary>
     public bool Own {get;set;}
+    /// <summary>Whether the native list wrapped owns the content it points to.</summary>
     public bool OwnContent {get;set;}
 
     /// <summary>Delegate for comparing two elements of this list.</summary>
     /// <returns>-1, 0 or 1 for respectively smaller, equal or larger.</returns>
     public delegate int Compare(T a, T b);
 
+    /// <summary>The number of elements on this list.</summary>
     public int Length
     {
         get { return Count(); }
@@ -153,11 +161,14 @@ public class List<T> : IEnumerable<T>, IDisposable
     }
 
 
+    /// <summary>Creates a new empty list.</summary>
     public List()
     {
         InitNew();
     }
 
+    /// <summary>Creates a new list wrapping the given handle.</summary>
+    [EditorBrowsable(EditorBrowsableState.Never)]
     public List(IntPtr handle, bool own)
     {
         Handle = handle;
@@ -165,6 +176,8 @@ public class List<T> : IEnumerable<T>, IDisposable
         OwnContent = own;
     }
 
+    /// <summary>Creates a new list wrapping the given handle.</summary>
+    [EditorBrowsable(EditorBrowsableState.Never)]
     public List(IntPtr handle, bool own, bool ownContent)
     {
         Handle = handle;
@@ -172,11 +185,15 @@ public class List<T> : IEnumerable<T>, IDisposable
         OwnContent = ownContent;
     }
 
+    /// <summary>Finalizes this list.</summary>
     ~List()
     {
         Dispose(false);
     }
 
+    /// <summary>Disposes of this list.</summary>
+    /// <param name="disposing">Whether this was called from the finalizer (<c>false</c>) or from the
+    /// <see cref="Dispose()"/> method.</param>
     protected virtual void Dispose(bool disposing)
     {
         IntPtr h = Handle;
@@ -207,17 +224,21 @@ public class List<T> : IEnumerable<T>, IDisposable
         }
     }
 
+    /// <summary>Disposes of this list.</summary>
     public void Dispose()
     {
         Dispose(true);
         GC.SuppressFinalize(this);
     }
 
+    /// <summary>Disposes of this list.</summary>
     public void Free()
     {
         Dispose();
     }
 
+    /// <summary>Relinquishes of the native list.</summary>
+    /// <returns>The previously wrapped native list handle.</returns>
     public IntPtr Release()
     {
         IntPtr h = Handle;
@@ -225,57 +246,77 @@ public class List<T> : IEnumerable<T>, IDisposable
         return h;
     }
 
+    /// <summary>Sets whether this wrapper should own the native list or not.</summary>
     public void SetOwnership(bool ownAll)
     {
         Own = ownAll;
         OwnContent = ownAll;
     }
 
+    /// <summary>Sets whether this wrapper should own the native list and its content or not.</summary>
     public void SetOwnership(bool own, bool ownContent)
     {
         Own = own;
         OwnContent = ownContent;
     }
 
+    /// <summary>Returns the number of elements in this list.</summary>
     public int Count()
     {
         return (int)eina_list_count_custom_export_mono(Handle);
     }
 
+    /// <summary>Appends <c>val</c> to the list.</summary>
+    /// <param name="val">The item to be appended.</param>
     public void Append(T val)
     {
         IntPtr ele = ManagedToNativeAlloc(val);
         Handle = eina_list_append(Handle, ele);
     }
 
+    /// <summary>Prepends <c>val</c> to the list.</summary>
+    /// <param name="val">The item to be prepended.</param>
     public void Prepend(T val)
     {
         IntPtr ele = ManagedToNativeAlloc(val);
         Handle = eina_list_prepend(Handle, ele);
     }
 
+    /// <summary>Inserts <c>val</c> in the list in a sorted manner. It presumes the list is already sorted.</summary>
+    /// <param name="val">The item to be inserted.</param>
     public void SortedInsert(T val)
     {
         IntPtr ele = ManagedToNativeAlloc(val);
         Handle = eina_list_sorted_insert(Handle, EinaCompareCb<T>(), ele);
     }
 
+    /// <summary>Inserts <c>val</c> in the list in a sorted manner with the given <c>compareCb</c> for element comparison.
+    /// It presumes the list is already sorted.</summary>
+    /// <param name="compareCb">The function to compare two elements of the list.</param>
+    /// <param name="val">The item to be inserted.</param>
     public void SortedInsert(Compare compareCb, T val)
     {
         IntPtr ele = ManagedToNativeAlloc(val);
         Handle = eina_list_sorted_insert(Handle, Marshal.GetFunctionPointerForDelegate(GetNativeCompareCb(compareCb)), ele);
     }
 
+    /// <summary>Sorts <c>limit</c> elements in this list inplace.</summary>
+    /// <param name="limit">The max number of elements to be sorted.</param>
     public void Sort(int limit = 0)
     {
         Handle = eina_list_sort(Handle, (uint)limit, EinaCompareCb<T>());
     }
 
+    /// <summary>Sorts all elements in this list inplace.</summary>
+    /// <param name="compareCb">The function to compare two elements of the list.</param>
     public void Sort(Compare compareCb)
     {
         Handle = eina_list_sort(Handle, 0, Marshal.GetFunctionPointerForDelegate(GetNativeCompareCb(compareCb)));
     }
 
+    /// <summary>Sorts <c>limit</c> elements in this list inplace.</summary>
+    /// <param name="limit">The max number of elements to be sorted.</param>
+    /// <param name="compareCb">The function to compare two elements of the list.</param>
     public void Sort(int limit, Compare compareCb)
     {
         Handle = eina_list_sort(Handle, (uint)limit, Marshal.GetFunctionPointerForDelegate(GetNativeCompareCb(compareCb)));
@@ -288,6 +329,9 @@ public class List<T> : IEnumerable<T>, IDisposable
         };
     }
 
+    /// <summary>Returns the <c>n</c>th element of this list. Due to marshalling details, the returned element
+    /// may be a different C# object from the one you used to append.</summary>
+    /// <param name="n">The 0-based index to be retrieved.</param>
     public T Nth(int n)
     {
         // TODO: check bounds ???
@@ -295,6 +339,9 @@ public class List<T> : IEnumerable<T>, IDisposable
         return NativeToManaged<T>(ele);
     }
 
+    /// <summary>Sets the data at the <c>idx</c> position.</summary>
+    /// <param name="idx">The 0-based index to be set.</param>
+    /// <param name="val">The value to be inserted.</param>
     public void DataSet(int idx, T val)
     {
         IntPtr pos = eina_list_nth_list(Handle, (uint)idx);
@@ -312,6 +359,8 @@ public class List<T> : IEnumerable<T>, IDisposable
         InternalDataSet(pos, ele);
     }
 
+    /// <summary>Accessor for the data at the <c>idx</c> position.</summary>
+    /// <param name="idx">The 0-based index to be get/set.</param>
     public T this[int idx]
     {
         get
@@ -324,23 +373,30 @@ public class List<T> : IEnumerable<T>, IDisposable
         }
     }
 
+    /// <summary>Returns the data at the last list element.</summary>
+    /// <returns>The value contained in the last list position.</returns>
     public T LastDataGet()
     {
         IntPtr ele = eina_list_last_data_get_custom_export_mono(Handle);
         return NativeToManaged<T>(ele);
     }
 
+    /// <summary>Reverses this list in place.</summary>
+    /// <returns>A reference to this object.</returns>
     public List<T> Reverse()
     {
         Handle = eina_list_reverse(Handle);
         return this;
     }
 
+    /// <summary>Randomly shuffles this list in place.</summary>
     public void Shuffle()
     {
         Handle = eina_list_shuffle(Handle, IntPtr.Zero);
     }
 
+    /// <summary>Gets a C# array of the elements in this list.</summary>
+    /// <returns>A managed array of the elements.</returns>
     public T[] ToArray()
     {
         var managed = new T[Count()];
@@ -353,6 +409,8 @@ public class List<T> : IEnumerable<T>, IDisposable
         return managed;
     }
 
+    /// <summary>Appends the given array of elements to this list.</summary>
+    /// <param name="values">The values to be appended.</param>
     public void AppendArray(T[] values)
     {
         foreach (T v in values)
@@ -362,16 +420,22 @@ public class List<T> : IEnumerable<T>, IDisposable
     }
 
 
+    /// <summary>Gets an iterator that iterates this list in normal order.</summary>
+    /// <returns>The iterator.</returns>
     public Eina.Iterator<T> GetIterator()
     {
         return new Eina.Iterator<T>(eina_list_iterator_new(Handle), true);
     }
 
+    /// <summary>Gets an iterator that iterates this list in reverse order.</summary>
+    /// <returns>The iterator.</returns>
     public Eina.Iterator<T> GetReversedIterator()
     {
         return new Eina.Iterator<T>(eina_list_iterator_reversed_new(Handle), true);
     }
 
+    /// <summary>Gets an enumerator into this list.</summary>
+    /// <returns>The enumerator.</returns>
     public IEnumerator<T> GetEnumerator()
     {
         for (IntPtr curr = Handle; curr != IntPtr.Zero; curr = InternalNext(curr))
@@ -380,12 +444,15 @@ public class List<T> : IEnumerable<T>, IDisposable
         }
     }
 
+    /// <summary>Gets an enumerator into this list.</summary>
+    /// <returns>The enumerator.</returns>
     System.Collections.IEnumerator System.Collections.IEnumerable.GetEnumerator()
     {
         return this.GetEnumerator();
     }
 
     /// <summary> Gets an Accessor for this List.</summary>
+    /// <returns>The accessor.</returns>
     public Eina.Accessor<T> GetAccessor()
     {
         return new Eina.Accessor<T>(eina_list_accessor_new(Handle), Ownership.Managed);