From 288e3e3af2ab1aff10035eb72b23628568541883 Mon Sep 17 00:00:00 2001
From: DE-YU_H14 <delsin_yu@qq.com>
Date: Fri, 14 Feb 2025 08:11:39 +0800
Subject: [PATCH] Improve documentation for C# typed collection wrappers

---
 modules/mono/glue/GodotSharp/GodotSharp/Core/Array.cs | 11 ++++++++---
 .../glue/GodotSharp/GodotSharp/Core/Dictionary.cs     | 11 ++++++++---
 2 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Array.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Array.cs
index 9879a78104..f83c551324 100644
--- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Array.cs
+++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Array.cs
@@ -1035,12 +1035,17 @@ namespace Godot.Collections
     }
 
     /// <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
+    /// Typed wrapper around Godot's Array class, an array of <typeparamref name="T"/>
+    /// annotated, 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>
+    /// <remarks>
+    /// While the elements are statically annotated to <typeparamref name="T"/>,
+    /// the underlying array still stores <see cref="Variant"/>, which has the same
+    /// memory footprint per element as an untyped <see cref="Array"/>.
+    /// </remarks>
     [DebuggerTypeProxy(typeof(ArrayDebugView<>))]
     [DebuggerDisplay("Count = {Count}")]
     [SuppressMessage("ReSharper", "RedundantExtendsListEntry")]
diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Dictionary.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Dictionary.cs
index dcb94f05fd..ee337b5e06 100644
--- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Dictionary.cs
+++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Dictionary.cs
@@ -476,13 +476,18 @@ namespace Godot.Collections
     }
 
     /// <summary>
-    /// 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
+    /// Typed wrapper around Godot's Dictionary class, a dictionary of <typeparamref name="TKey"/>
+    /// and <typeparamref name="TValue"/> annotated, Variant typed elements allocated in the engine in C++.
+    /// Useful when interfacing with the engine. Otherwise prefer .NET collections
     /// such as <see cref="System.Collections.Generic.Dictionary{TKey, TValue}"/>.
     /// </summary>
     /// <typeparam name="TKey">The type of the dictionary's keys.</typeparam>
     /// <typeparam name="TValue">The type of the dictionary's values.</typeparam>
+    /// <remarks>
+    /// While the elements are statically annotated to <typeparamref name="TKey"/> and <typeparamref name="TValue"/>,
+    /// the underlying dictionary still stores <see cref="Variant"/>, which has the same memory footprint per element
+    /// as an untyped <see cref="Dictionary"/>.
+    /// </remarks>
     [DebuggerTypeProxy(typeof(DictionaryDebugView<,>))]
     [DebuggerDisplay("Count = {Count}")]
     [SuppressMessage("Design", "CA1001", MessageId = "Types that own disposable fields should be disposable",