From ca32c184587c702a0a0cd9091aa6144edacd8d80 Mon Sep 17 00:00:00 2001 From: Raul Santos Date: Wed, 28 Jul 2021 15:44:09 +0200 Subject: [PATCH] Add documentation to Dictionary in C# Adds documentation to `Godot.Collections.Dictionary` in C#. (cherry picked from commit 0669ffcd157dffb3e284457e968e617431badfd7) --- .../GodotSharp/GodotSharp/Core/Dictionary.cs | 188 ++++++++++++++++-- 1 file changed, 168 insertions(+), 20 deletions(-) diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Dictionary.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Dictionary.cs index 213fc181c1d..3d98445b141 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Dictionary.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Dictionary.cs @@ -3,6 +3,7 @@ using System.Collections.Generic; using System.Collections; using System.Runtime.CompilerServices; using System.Runtime.InteropServices; +using System.Diagnostics.CodeAnalysis; namespace Godot.Collections { @@ -25,6 +26,11 @@ namespace Godot.Collections } } + /// + /// Wrapper around Godot's Dictionary class, a dictionary of Variant + /// typed elements allocated in the engine in C++. Useful when + /// interfacing with the engine. + /// public class Dictionary : IDictionary, IDisposable @@ -32,11 +38,19 @@ namespace Godot.Collections DictionarySafeHandle safeHandle; bool disposed = false; + /// + /// Constructs a new empty . + /// public Dictionary() { safeHandle = new DictionarySafeHandle(godot_icall_Dictionary_Ctor()); } + /// + /// Constructs a new from the given dictionary's elements. + /// + /// The dictionary to construct from. + /// A new Godot Dictionary. public Dictionary(IDictionary dictionary) : this() { if (dictionary == null) @@ -64,6 +78,9 @@ namespace Godot.Collections return safeHandle.DangerousGetHandle(); } + /// + /// Disposes of this . + /// public void Dispose() { if (disposed) @@ -78,6 +95,11 @@ namespace Godot.Collections disposed = true; } + /// + /// Duplicates this . + /// + /// If , performs a deep copy. + /// A new Godot Dictionary. public Dictionary Duplicate(bool deep = false) { return new Dictionary(godot_icall_Dictionary_Duplicate(GetPtr(), deep)); @@ -85,6 +107,9 @@ namespace Godot.Collections // IDictionary + /// + /// Gets the collection of keys in this . + /// public ICollection Keys { get @@ -94,6 +119,9 @@ namespace Godot.Collections } } + /// + /// Gets the collection of elements in this . + /// public ICollection Values { get @@ -103,34 +131,71 @@ namespace Godot.Collections } } - public bool IsFixedSize => false; + bool IDictionary.IsFixedSize => false; - public bool IsReadOnly => false; + bool IDictionary.IsReadOnly => false; + /// + /// Returns the object at the given . + /// + /// The object at the given . public object this[object key] { get => godot_icall_Dictionary_GetValue(GetPtr(), key); set => godot_icall_Dictionary_SetValue(GetPtr(), key, value); } + /// + /// Adds an object at key + /// to this . + /// + /// The key at which to add the object. + /// The object to add. public void Add(object key, object value) => godot_icall_Dictionary_Add(GetPtr(), key, value); + /// + /// Erases all items from this . + /// public void Clear() => godot_icall_Dictionary_Clear(GetPtr()); + /// + /// Checks if this contains the given key. + /// + /// The key to look for. + /// Whether or not this dictionary contains the given key. public bool Contains(object key) => godot_icall_Dictionary_ContainsKey(GetPtr(), key); + /// + /// Gets an enumerator for this . + /// + /// An enumerator. public IDictionaryEnumerator GetEnumerator() => new DictionaryEnumerator(this); + /// + /// Removes an element from this by key. + /// + /// The key of the element to remove. public void Remove(object key) => godot_icall_Dictionary_RemoveKey(GetPtr(), key); // ICollection - public object SyncRoot => this; + object ICollection.SyncRoot => this; - public bool IsSynchronized => false; + bool ICollection.IsSynchronized => false; + /// + /// Returns the number of elements in this . + /// This is also known as the size or length of the dictionary. + /// + /// The number of elements. public int Count => godot_icall_Dictionary_Count(GetPtr()); + /// + /// 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) { // TODO Can be done with single internal call @@ -161,10 +226,10 @@ namespace Godot.Collections private class DictionaryEnumerator : IDictionaryEnumerator { - Array keys; - Array values; - int count; - int index = -1; + private readonly Array keys; + private readonly Array values; + private readonly int count; + private int index = -1; public DictionaryEnumerator(Dictionary dictionary) { @@ -196,6 +261,10 @@ namespace Godot.Collections } } + /// + /// Converts this to a string. + /// + /// A string representation of this dictionary. public override string ToString() { return godot_icall_Dictionary_ToString(GetPtr()); @@ -259,10 +328,18 @@ namespace Godot.Collections internal extern static string godot_icall_Dictionary_ToString(IntPtr ptr); } + /// + /// Typed wrapper around Godot's Dictionary class, a dictionary of Variant + /// typed elements allocated in the engine in C++. Useful when + /// interfacing with the engine. Otherwise prefer .NET collections + /// such as . + /// + /// The type of the dictionary's keys. + /// The type of the dictionary's values. public class Dictionary : IDictionary { - Dictionary objectDict; + private readonly Dictionary objectDict; internal static int valTypeEncoding; internal static IntPtr valTypeClass; @@ -272,11 +349,19 @@ namespace Godot.Collections Dictionary.godot_icall_Dictionary_Generic_GetValueTypeInfo(typeof(TValue), out valTypeEncoding, out valTypeClass); } + /// + /// Constructs a new empty . + /// public Dictionary() { objectDict = new Dictionary(); } + /// + /// Constructs a new from the given dictionary's elements. + /// + /// The dictionary to construct from. + /// A new Godot Dictionary. public Dictionary(IDictionary dictionary) { objectDict = new Dictionary(); @@ -294,6 +379,11 @@ namespace Godot.Collections } } + /// + /// Constructs a new from the given dictionary's elements. + /// + /// The dictionary to construct from. + /// A new Godot Dictionary. public Dictionary(Dictionary dictionary) { objectDict = dictionary; @@ -309,6 +399,10 @@ namespace Godot.Collections objectDict = new Dictionary(handle); } + /// + /// Converts this typed to an untyped . + /// + /// The typed dictionary to convert. public static explicit operator Dictionary(Dictionary from) { return from.objectDict; @@ -319,6 +413,11 @@ namespace Godot.Collections return objectDict.GetPtr(); } + /// + /// Duplicates this . + /// + /// If , performs a deep copy. + /// A new Godot Dictionary. public Dictionary Duplicate(bool deep = false) { return new Dictionary(objectDict.Duplicate(deep)); @@ -326,12 +425,19 @@ namespace Godot.Collections // IDictionary + /// + /// Returns the value at the given . + /// + /// The value at the given . public TValue this[TKey key] { get { return (TValue)Dictionary.godot_icall_Dictionary_GetValue_Generic(objectDict.GetPtr(), key, valTypeEncoding, valTypeClass); } set { objectDict[key] = value; } } + /// + /// Gets the collection of keys in this . + /// public ICollection Keys { get @@ -341,6 +447,9 @@ namespace Godot.Collections } } + /// + /// Gets the collection of elements in this . + /// public ICollection Values { get @@ -350,56 +459,87 @@ namespace Godot.Collections } } + /// + /// Adds an object at key + /// to this . + /// + /// The key at which to add the object. + /// The object to add. public void Add(TKey key, TValue value) { objectDict.Add(key, value); } + /// + /// Checks if this contains the given key. + /// + /// The key to look for. + /// Whether or not this dictionary contains the given key. public bool ContainsKey(TKey key) { return objectDict.Contains(key); } + /// + /// Removes an element from this by key. + /// + /// The key of the element to remove. public bool Remove(TKey key) { return Dictionary.godot_icall_Dictionary_RemoveKey(GetPtr(), key); } - public bool TryGetValue(TKey key, out TValue value) + /// + /// Gets the object at the given . + /// + /// The key of the element to get. + /// The value at the given . + /// If an object was found for the given . + public bool TryGetValue(TKey key, [MaybeNullWhen(false)] out TValue value) { - object retValue; - bool found = Dictionary.godot_icall_Dictionary_TryGetValue_Generic(GetPtr(), key, out retValue, valTypeEncoding, valTypeClass); - value = found ? (TValue)retValue : default(TValue); + bool found = Dictionary.godot_icall_Dictionary_TryGetValue_Generic(GetPtr(), key, out object retValue, valTypeEncoding, valTypeClass); + value = found ? (TValue)retValue : default; return found; } // ICollection> + /// + /// Returns the number of elements in this . + /// This is also known as the size or length of the dictionary. + /// + /// The number of elements. public int Count { get { return objectDict.Count; } } - public bool IsReadOnly - { - get { return objectDict.IsReadOnly; } - } + bool ICollection>.IsReadOnly => false; - public void Add(KeyValuePair item) + void ICollection>.Add(KeyValuePair item) { objectDict.Add(item.Key, item.Value); } + /// + /// Erases all the items from this . + /// public void Clear() { objectDict.Clear(); } - public bool Contains(KeyValuePair item) + bool ICollection>.Contains(KeyValuePair item) { return objectDict.Contains(new KeyValuePair(item.Key, item.Value)); } + /// + /// 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(KeyValuePair[] array, int arrayIndex) { if (array == null) @@ -424,7 +564,7 @@ namespace Godot.Collections } } - public bool Remove(KeyValuePair item) + bool ICollection>.Remove(KeyValuePair item) { return Dictionary.godot_icall_Dictionary_Remove(GetPtr(), item.Key, item.Value); ; @@ -432,6 +572,10 @@ namespace Godot.Collections // IEnumerable> + /// + /// Gets an enumerator for this . + /// + /// An enumerator. public IEnumerator> GetEnumerator() { // TODO 3 internal calls, can reduce to 1 @@ -451,6 +595,10 @@ namespace Godot.Collections return GetEnumerator(); } + /// + /// Converts this to a string. + /// + /// A string representation of this dictionary. public override string ToString() => objectDict.ToString(); } }