From 080f44a3b711f7a78fc2f318fd5dca095202bce5 Mon Sep 17 00:00:00 2001 From: Aaron Franke Date: Sun, 25 Jul 2021 14:41:57 -0400 Subject: [PATCH] Add documentation to Array in C# --- .../glue/GodotSharp/GodotSharp/Core/Array.cs | 222 +++++++++++++++++- 1 file 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 ce613f7ef92..f52a767018b 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 } } + /// + /// 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 or . + /// public class Array : IList, IDisposable { ArraySafeHandle safeHandle; bool disposed = false; + /// + /// Constructs a new empty . + /// public Array() { safeHandle = new ArraySafeHandle(godot_icall_Array_Ctor()); } + /// + /// Constructs a new from the given collection's elements. + /// + /// The collection of elements to construct from. + /// A new Godot Array. public Array(IEnumerable collection) : this() { if (collection == null) @@ -44,6 +58,11 @@ namespace Godot.Collections Add(element); } + /// + /// Constructs a new from the given objects. + /// + /// The objects to put in the new array. + /// A new Godot Array. public Array(params object[] array) : this() { if (array == null) @@ -71,21 +90,40 @@ namespace Godot.Collections return safeHandle.DangerousGetHandle(); } + /// + /// Duplicates this . + /// + /// If true, performs a deep copy. + /// A new Godot Array. public Array Duplicate(bool deep = false) { return new Array(godot_icall_Array_Duplicate(GetPtr(), deep)); } + /// + /// Resizes this to the given size. + /// + /// The new size of the array. + /// if successful, or an error code. public Error Resize(int newSize) { return godot_icall_Array_Resize(GetPtr(), newSize); } + /// + /// Shuffles the contents of this into a random order. + /// public void Shuffle() { godot_icall_Array_Shuffle(GetPtr()); } + /// + /// Concatenates these two s. + /// + /// The first array. + /// The second array. + /// A new Godot Array with the contents of both arrays. 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 + /// + /// Disposes of this . + /// 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; + /// + /// Returns the object at the given index. + /// + /// The object at the given index. public object this[int index] { get => godot_icall_Array_At(GetPtr(), index); set => godot_icall_Array_SetAt(GetPtr(), index, value); } + /// + /// Adds an object to the end of this . + /// This is the same as `append` or `push_back` in GDScript. + /// + /// The object to add. + /// The new size after adding the object. public int Add(object value) => godot_icall_Array_Add(GetPtr(), value); + /// + /// Checks if this contains the given object. + /// + /// The item to look for. + /// Whether or not this array contains the given object. public bool Contains(object value) => godot_icall_Array_Contains(GetPtr(), value); + /// + /// Erases all items from this . + /// public void Clear() => godot_icall_Array_Clear(GetPtr()); + /// + /// Searches this for an object + /// and returns its index or -1 if not found. + /// + /// The object to search for. + /// The index of the object, or -1 if not found. public int IndexOf(object value) => godot_icall_Array_IndexOf(GetPtr(), value); + /// + /// 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. + /// + /// The index to insert at. + /// The object to insert. public void Insert(int index, object value) => godot_icall_Array_Insert(GetPtr(), index, value); + /// + /// Removes the first occurrence of the specified value + /// from this . + /// + /// The value to remove. public void Remove(object value) => godot_icall_Array_Remove(GetPtr(), value); + /// + /// Removes an element from this by index. + /// + /// The index of the element to remove. public void RemoveAt(int index) => godot_icall_Array_RemoveAt(GetPtr(), index); // ICollection + /// + /// Returns the number of elements in this . + /// This is also known as the size or length of the array. + /// + /// The number of elements. public int Count => godot_icall_Array_Count(GetPtr()); - public object SyncRoot => this; + object ICollection.SyncRoot => this; - public bool IsSynchronized => false; + bool ICollection.IsSynchronized => false; + /// + /// Copies the elements of this to the given + /// untyped C# array, starting at the given index. + /// + /// The array to copy to. + /// The index to start at. public void CopyTo(System.Array array, int index) { if (array == null) @@ -155,6 +248,10 @@ namespace Godot.Collections // IEnumerable + /// + /// Gets an enumerator for this . + /// + /// An enumerator. public IEnumerator GetEnumerator() { int count = Count; @@ -165,6 +262,10 @@ namespace Godot.Collections } } + /// + /// Converts this to a string. + /// + /// A string representation of this array. 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); } + /// + /// 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 . + /// + /// The type of the array. public class Array : IList, ICollection, IEnumerable { Array objectArray; @@ -246,11 +354,19 @@ namespace Godot.Collections Array.godot_icall_Array_Generic_GetElementTypeInfo(typeof(T), out elemTypeEncoding, out elemTypeClass); } + /// + /// Constructs a new empty . + /// public Array() { objectArray = new Array(); } + /// + /// Constructs a new from the given collection's elements. + /// + /// The collection of elements to construct from. + /// A new Godot Array. public Array(IEnumerable collection) { if (collection == null) @@ -259,6 +375,11 @@ namespace Godot.Collections objectArray = new Array(collection); } + /// + /// Constructs a new from the given items. + /// + /// The items to put in the new array. + /// A new Godot Array. public Array(params T[] array) : this() { if (array == null) @@ -268,6 +389,10 @@ namespace Godot.Collections objectArray = new Array(array); } + /// + /// Constructs a typed from an untyped . + /// + /// The untyped array to construct from. public Array(Array array) { objectArray = array; @@ -288,26 +413,49 @@ namespace Godot.Collections return objectArray.GetPtr(); } + /// + /// Converts this typed to an untyped . + /// + /// The typed array to convert. public static explicit operator Array(Array from) { return from.objectArray; } + /// + /// Duplicates this . + /// + /// If true, performs a deep copy. + /// A new Godot Array. public Array Duplicate(bool deep = false) { return new Array(objectArray.Duplicate(deep)); } + /// + /// Resizes this to the given size. + /// + /// The new size of the array. + /// if successful, or an error code. public Error Resize(int newSize) { return objectArray.Resize(newSize); } + /// + /// Shuffles the contents of this into a random order. + /// public void Shuffle() { objectArray.Shuffle(); } + /// + /// Concatenates these two s. + /// + /// The first array. + /// The second array. + /// A new Godot Array with the contents of both arrays. public static Array operator +(Array left, Array right) { return new Array(left.objectArray + right.objectArray); @@ -315,22 +463,44 @@ namespace Godot.Collections // IList + /// + /// Returns the value at the given index. + /// + /// The value at the given index. public T this[int index] { get { return (T)Array.godot_icall_Array_At_Generic(GetPtr(), index, elemTypeEncoding, elemTypeClass); } set { objectArray[index] = value; } } + /// + /// Searches this for an item + /// and returns its index or -1 if not found. + /// + /// The item to search for. + /// The index of the item, or -1 if not found. public int IndexOf(T item) { return objectArray.IndexOf(item); } + /// + /// Inserts a new item at a given position in the . + /// 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. + /// + /// The index to insert at. + /// The item to insert. public void Insert(int index, T item) { objectArray.Insert(index, item); } + /// + /// Removes an element from this by index. + /// + /// The index of the element to remove. public void RemoveAt(int index) { objectArray.RemoveAt(index); @@ -338,31 +508,53 @@ namespace Godot.Collections // ICollection + /// + /// Returns the number of elements in this . + /// This is also known as the size or length of the array. + /// + /// The number of elements. public int Count { get { return objectArray.Count; } } - public bool IsReadOnly - { - get { return objectArray.IsReadOnly; } - } + bool ICollection.IsReadOnly => false; + /// + /// Adds an item to the end of this . + /// This is the same as `append` or `push_back` in GDScript. + /// + /// The item to add. + /// The new size after adding the item. public void Add(T item) { objectArray.Add(item); } + /// + /// Erases all items from this . + /// public void Clear() { objectArray.Clear(); } + /// + /// Checks if this contains the given item. + /// + /// The item to look for. + /// Whether or not this array contains the given item. public bool Contains(T item) { return objectArray.Contains(item); } + /// + /// Copies the elements of this to the given + /// C# array, starting at the given index. + /// + /// The C# array to copy to. + /// The index to start at. public void CopyTo(T[] array, int arrayIndex) { if (array == null) @@ -386,6 +578,12 @@ namespace Godot.Collections } } + /// + /// Removes the first occurrence of the specified value + /// from this . + /// + /// The value to remove. + /// A bool indicating success or failure. public bool Remove(T item) { return Array.godot_icall_Array_Remove(GetPtr(), item); @@ -393,6 +591,10 @@ namespace Godot.Collections // IEnumerable + /// + /// Gets an enumerator for this . + /// + /// An enumerator. public IEnumerator GetEnumerator() { int count = objectArray.Count; @@ -408,6 +610,10 @@ namespace Godot.Collections return GetEnumerator(); } + /// + /// Converts this to a string. + /// + /// A string representation of this array. public override string ToString() => objectArray.ToString(); } }