Merge pull request #50867 from aaronfranke/cs-array-empty

Add documentation to Array in C#

1 files changed, 214 insertions, 8 deletions

diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Array.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Array.cs
index ce613f7ef9..f52a767018 100644
--- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Array.cs
+++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Array.cs
@@ -25,16 +25,30 @@ namespace Godot.Collections
         }
     }
 
+    /// <summary>
+    /// Wrapper around Godot's Array class, an array of Variant
+    /// typed elements allocated in the engine in C++. Useful when
+    /// interfacing with the engine. Otherwise prefer .NET collections
+    /// such as <see cref="System.Array"/> or <see cref="List{T}"/>.
+    /// </summary>
     public class Array : IList, IDisposable
     {
         ArraySafeHandle safeHandle;
         bool disposed = false;
 
+        /// <summary>
+        /// Constructs a new empty <see cref="Array"/>.
+        /// </summary>
         public Array()
         {
             safeHandle = new ArraySafeHandle(godot_icall_Array_Ctor());
         }
 
+        /// <summary>
+        /// Constructs a new <see cref="Array"/> from the given collection's elements.
+        /// </summary>
+        /// <param name="collection">The collection of elements to construct from.</param>
+        /// <returns>A new Godot Array.</returns>
         public Array(IEnumerable collection) : this()
         {
             if (collection == null)
@@ -44,6 +58,11 @@ namespace Godot.Collections
                 Add(element);
         }
 
+        /// <summary>
+        /// Constructs a new <see cref="Array"/> from the given objects.
+        /// </summary>
+        /// <param name="array">The objects to put in the new array.</param>
+        /// <returns>A new Godot Array.</returns>
         public Array(params object[] array) : this()
         {
             if (array == null)
@@ -71,21 +90,40 @@ namespace Godot.Collections
             return safeHandle.DangerousGetHandle();
         }
 
+        /// <summary>
+        /// Duplicates this <see cref="Array"/>.
+        /// </summary>
+        /// <param name="deep">If true, performs a deep copy.</param>
+        /// <returns>A new Godot Array.</returns>
         public Array Duplicate(bool deep = false)
         {
             return new Array(godot_icall_Array_Duplicate(GetPtr(), deep));
         }
 
+        /// <summary>
+        /// Resizes this <see cref="Array"/> to the given size.
+        /// </summary>
+        /// <param name="newSize">The new size of the array.</param>
+        /// <returns><see cref="Error.Ok"/> if successful, or an error code.</returns>
         public Error Resize(int newSize)
         {
             return godot_icall_Array_Resize(GetPtr(), newSize);
         }
 
+        /// <summary>
+        /// Shuffles the contents of this <see cref="Array"/> into a random order.
+        /// </summary>
         public void Shuffle()
         {
             godot_icall_Array_Shuffle(GetPtr());
         }
 
+        /// <summary>
+        /// Concatenates these two <see cref="Array"/>s.
+        /// </summary>
+        /// <param name="left">The first array.</param>
+        /// <param name="right">The second array.</param>
+        /// <returns>A new Godot Array with the contents of both arrays.</returns>
         public static Array operator +(Array left, Array right)
         {
             return new Array(godot_icall_Array_Concatenate(left.GetPtr(), right.GetPtr()));
@@ -93,6 +131,9 @@ namespace Godot.Collections
 
         // IDisposable
 
+        /// <summary>
+        /// Disposes of this <see cref="Array"/>.
+        /// </summary>
         public void Dispose()
         {
             if (disposed)
@@ -109,38 +150,90 @@ namespace Godot.Collections
 
         // IList
 
-        public bool IsReadOnly => false;
+        bool IList.IsReadOnly => false;
 
-        public bool IsFixedSize => false;
+        bool IList.IsFixedSize => false;
 
+        /// <summary>
+        /// Returns the object at the given index.
+        /// </summary>
+        /// <value>The object at the given index.</value>
         public object this[int index]
         {
             get => godot_icall_Array_At(GetPtr(), index);
             set => godot_icall_Array_SetAt(GetPtr(), index, value);
         }
 
+        /// <summary>
+        /// Adds an object to the end of this <see cref="Array"/>.
+        /// This is the same as `append` or `push_back` in GDScript.
+        /// </summary>
+        /// <param name="value">The object to add.</param>
+        /// <returns>The new size after adding the object.</returns>
         public int Add(object value) => godot_icall_Array_Add(GetPtr(), value);
 
+        /// <summary>
+        /// Checks if this <see cref="Array"/> contains the given object.
+        /// </summary>
+        /// <param name="value">The item to look for.</param>
+        /// <returns>Whether or not this array contains the given object.</returns>
         public bool Contains(object value) => godot_icall_Array_Contains(GetPtr(), value);
 
+        /// <summary>
+        /// Erases all items from this <see cref="Array"/>.
+        /// </summary>
         public void Clear() => godot_icall_Array_Clear(GetPtr());
 
+        /// <summary>
+        /// Searches this <see cref="Array"/> for an object
+        /// and returns its index or -1 if not found.
+        /// </summary>
+        /// <param name="value">The object to search for.</param>
+        /// <returns>The index of the object, or -1 if not found.</returns>
         public int IndexOf(object value) => godot_icall_Array_IndexOf(GetPtr(), value);
 
+        /// <summary>
+        /// Inserts a new object at a given position in the array.
+        /// The position must be a valid position of an existing item,
+        /// or the position at the end of the array.
+        /// Existing items will be moved to the right.
+        /// </summary>
+        /// <param name="index">The index to insert at.</param>
+        /// <param name="value">The object to insert.</param>
         public void Insert(int index, object value) => godot_icall_Array_Insert(GetPtr(), index, value);
 
+        /// <summary>
+        /// Removes the first occurrence of the specified value
+        /// from this <see cref="Array"/>.
+        /// </summary>
+        /// <param name="value">The value to remove.</param>
         public void Remove(object value) => godot_icall_Array_Remove(GetPtr(), value);
 
+        /// <summary>
+        /// Removes an element from this <see cref="Array"/> by index.
+        /// </summary>
+        /// <param name="index">The index of the element to remove.</param>
         public void RemoveAt(int index) => godot_icall_Array_RemoveAt(GetPtr(), index);
 
         // ICollection
 
+        /// <summary>
+        /// Returns the number of elements in this <see cref="Array"/>.
+        /// This is also known as the size or length of the array.
+        /// </summary>
+        /// <returns>The number of elements.</returns>
         public int Count => godot_icall_Array_Count(GetPtr());
 
-        public object SyncRoot => this;
+        object ICollection.SyncRoot => this;
 
-        public bool IsSynchronized => false;
+        bool ICollection.IsSynchronized => false;
 
+        /// <summary>
+        /// Copies the elements of this <see cref="Array"/> to the given
+        /// untyped C# array, starting at the given index.
+        /// </summary>
+        /// <param name="array">The array to copy to.</param>
+        /// <param name="index">The index to start at.</param>
         public void CopyTo(System.Array array, int index)
         {
             if (array == null)
@@ -155,6 +248,10 @@ namespace Godot.Collections
 
         // IEnumerable
 
+        /// <summary>
+        /// Gets an enumerator for this <see cref="Array"/>.
+        /// </summary>
+        /// <returns>An enumerator.</returns>
         public IEnumerator GetEnumerator()
         {
             int count = Count;
@@ -165,6 +262,10 @@ namespace Godot.Collections
             }
         }
 
+        /// <summary>
+        /// Converts this <see cref="Array"/> to a string.
+        /// </summary>
+        /// <returns>A string representation of this array.</returns>
         public override string ToString()
         {
             return godot_icall_Array_ToString(GetPtr());
@@ -234,6 +335,13 @@ namespace Godot.Collections
         internal extern static string godot_icall_Array_ToString(IntPtr ptr);
     }
 
+    /// <summary>
+    /// Typed wrapper around Godot's Array class, an array of Variant
+    /// typed elements allocated in the engine in C++. Useful when
+    /// interfacing with the engine. Otherwise prefer .NET collections
+    /// such as arrays or <see cref="List{T}"/>.
+    /// </summary>
+    /// <typeparam name="T">The type of the array.</typeparam>
     public class Array<T> : IList<T>, ICollection<T>, IEnumerable<T>
     {
         Array objectArray;
@@ -246,11 +354,19 @@ namespace Godot.Collections
             Array.godot_icall_Array_Generic_GetElementTypeInfo(typeof(T), out elemTypeEncoding, out elemTypeClass);
         }
 
+        /// <summary>
+        /// Constructs a new empty <see cref="Array{T}"/>.
+        /// </summary>
         public Array()
         {
             objectArray = new Array();
         }
 
+        /// <summary>
+        /// Constructs a new <see cref="Array{T}"/> from the given collection's elements.
+        /// </summary>
+        /// <param name="collection">The collection of elements to construct from.</param>
+        /// <returns>A new Godot Array.</returns>
         public Array(IEnumerable<T> collection)
         {
             if (collection == null)
@@ -259,6 +375,11 @@ namespace Godot.Collections
             objectArray = new Array(collection);
         }
 
+        /// <summary>
+        /// Constructs a new <see cref="Array{T}"/> from the given items.
+        /// </summary>
+        /// <param name="array">The items to put in the new array.</param>
+        /// <returns>A new Godot Array.</returns>
         public Array(params T[] array) : this()
         {
             if (array == null)
@@ -268,6 +389,10 @@ namespace Godot.Collections
             objectArray = new Array(array);
         }
 
+        /// <summary>
+        /// Constructs a typed <see cref="Array{T}"/> from an untyped <see cref="Array"/>.
+        /// </summary>
+        /// <param name="array">The untyped array to construct from.</param>
         public Array(Array array)
         {
             objectArray = array;
@@ -288,26 +413,49 @@ namespace Godot.Collections
             return objectArray.GetPtr();
         }
 
+        /// <summary>
+        /// Converts this typed <see cref="Array{T}"/> to an untyped <see cref="Array"/>.
+        /// </summary>
+        /// <param name="from">The typed array to convert.</param>
         public static explicit operator Array(Array<T> from)
         {
             return from.objectArray;
         }
 
+        /// <summary>
+        /// Duplicates this <see cref="Array{T}"/>.
+        /// </summary>
+        /// <param name="deep">If true, performs a deep copy.</param>
+        /// <returns>A new Godot Array.</returns>
         public Array<T> Duplicate(bool deep = false)
         {
             return new Array<T>(objectArray.Duplicate(deep));
         }
 
+        /// <summary>
+        /// Resizes this <see cref="Array{T}"/> to the given size.
+        /// </summary>
+        /// <param name="newSize">The new size of the array.</param>
+        /// <returns><see cref="Error.Ok"/> if successful, or an error code.</returns>
         public Error Resize(int newSize)
         {
             return objectArray.Resize(newSize);
         }
 
+        /// <summary>
+        /// Shuffles the contents of this <see cref="Array{T}"/> into a random order.
+        /// </summary>
         public void Shuffle()
         {
             objectArray.Shuffle();
         }
 
+        /// <summary>
+        /// Concatenates these two <see cref="Array{T}"/>s.
+        /// </summary>
+        /// <param name="left">The first array.</param>
+        /// <param name="right">The second array.</param>
+        /// <returns>A new Godot Array with the contents of both arrays.</returns>
         public static Array<T> operator +(Array<T> left, Array<T> right)
         {
             return new Array<T>(left.objectArray + right.objectArray);
@@ -315,22 +463,44 @@ namespace Godot.Collections
 
         // IList<T>
 
+        /// <summary>
+        /// Returns the value at the given index.
+        /// </summary>
+        /// <value>The value at the given index.</value>
         public T this[int index]
         {
             get { return (T)Array.godot_icall_Array_At_Generic(GetPtr(), index, elemTypeEncoding, elemTypeClass); }
             set { objectArray[index] = value; }
         }
 
+        /// <summary>
+        /// Searches this <see cref="Array{T}"/> for an item
+        /// and returns its index or -1 if not found.
+        /// </summary>
+        /// <param name="item">The item to search for.</param>
+        /// <returns>The index of the item, or -1 if not found.</returns>
         public int IndexOf(T item)
         {
             return objectArray.IndexOf(item);
         }
 
+        /// <summary>
+        /// Inserts a new item at a given position in the <see cref="Array{T}"/>.
+        /// The position must be a valid position of an existing item,
+        /// or the position at the end of the array.
+        /// Existing items will be moved to the right.
+        /// </summary>
+        /// <param name="index">The index to insert at.</param>
+        /// <param name="item">The item to insert.</param>
         public void Insert(int index, T item)
         {
             objectArray.Insert(index, item);
         }
 
+        /// <summary>
+        /// Removes an element from this <see cref="Array{T}"/> by index.
+        /// </summary>
+        /// <param name="index">The index of the element to remove.</param>
         public void RemoveAt(int index)
         {
             objectArray.RemoveAt(index);
@@ -338,31 +508,53 @@ namespace Godot.Collections
 
         // ICollection<T>
 
+        /// <summary>
+        /// Returns the number of elements in this <see cref="Array{T}"/>.
+        /// This is also known as the size or length of the array.
+        /// </summary>
+        /// <returns>The number of elements.</returns>
         public int Count
         {
             get { return objectArray.Count; }
         }
 
-        public bool IsReadOnly
-        {
-            get { return objectArray.IsReadOnly; }
-        }
+        bool ICollection<T>.IsReadOnly => false;
 
+        /// <summary>
+        /// Adds an item to the end of this <see cref="Array{T}"/>.
+        /// This is the same as `append` or `push_back` in GDScript.
+        /// </summary>
+        /// <param name="item">The item to add.</param>
+        /// <returns>The new size after adding the item.</returns>
         public void Add(T item)
         {
             objectArray.Add(item);
         }
 
+        /// <summary>
+        /// Erases all items from this <see cref="Array{T}"/>.
+        /// </summary>
         public void Clear()
         {
             objectArray.Clear();
         }
 
+        /// <summary>
+        /// Checks if this <see cref="Array{T}"/> contains the given item.
+        /// </summary>
+        /// <param name="item">The item to look for.</param>
+        /// <returns>Whether or not this array contains the given item.</returns>
         public bool Contains(T item)
         {
             return objectArray.Contains(item);
         }
 
+        /// <summary>
+        /// Copies the elements of this <see cref="Array{T}"/> to the given
+        /// C# array, starting at the given index.
+        /// </summary>
+        /// <param name="array">The C# array to copy to.</param>
+        /// <param name="arrayIndex">The index to start at.</param>
         public void CopyTo(T[] array, int arrayIndex)
         {
             if (array == null)
@@ -386,6 +578,12 @@ namespace Godot.Collections
             }
         }
 
+        /// <summary>
+        /// Removes the first occurrence of the specified value
+        /// from this <see cref="Array{T}"/>.
+        /// </summary>
+        /// <param name="item">The value to remove.</param>
+        /// <returns>A bool indicating success or failure.</returns>
         public bool Remove(T item)
         {
             return Array.godot_icall_Array_Remove(GetPtr(), item);
@@ -393,6 +591,10 @@ namespace Godot.Collections
 
         // IEnumerable<T>
 
+        /// <summary>
+        /// Gets an enumerator for this <see cref="Array{T}"/>.
+        /// </summary>
+        /// <returns>An enumerator.</returns>
         public IEnumerator<T> GetEnumerator()
         {
             int count = objectArray.Count;
@@ -408,6 +610,10 @@ namespace Godot.Collections
             return GetEnumerator();
         }
 
+        /// <summary>
+        /// Converts this <see cref="Array{T}"/> to a string.
+        /// </summary>
+        /// <returns>A string representation of this array.</returns>
         public override string ToString() => objectArray.ToString();
     }
 }