From d856d5eb82492762a55655452ffb6d4b23851bcf Mon Sep 17 00:00:00 2001
From: Raul Santos <raulsntos@gmail.com>
Date: Sat, 4 Feb 2023 17:43:08 +0100
Subject: [PATCH] Update Variant documentation for C#

---
 doc/classes/Variant.xml | 33 ++++++++++++++++++++++-----------
 1 file changed, 22 insertions(+), 11 deletions(-)

diff --git a/doc/classes/Variant.xml b/doc/classes/Variant.xml
index 5416468ab6c..b1ce05888ae 100644
--- a/doc/classes/Variant.xml
+++ b/doc/classes/Variant.xml
@@ -14,16 +14,21 @@
 		# bar = "Uh oh! I can't make static variables become a different type!"
 		[/gdscript]
 		[csharp]
-		// ... but C# is statically typed. Once a variable has a type it cannot be changed. However you can use the var keyword in methods to let the compiler decide the type automatically.
-		var foo = 2; // Foo is a 32-bit integer (int). Be cautious, integers in GDScript are 64-bit and the direct C# equivalent is "long".
+		// C# is statically typed. Once a variable has a type it cannot be changed. You can use the `var` keyword to let the compiler infer the type automatically.
+		var foo = 2; // Foo is a 32-bit integer (int). Be cautious, integers in GDScript are 64-bit and the direct C# equivalent is `long`.
 		// foo = "foo was and will always be an integer. It cannot be turned into a string!";
 		var boo = "Boo is a string!";
-		var ref = new Reference(); // var is especially useful when used together with a constructor.
+		var ref = new RefCounted(); // var is especially useful when used together with a constructor.
+
+		// Godot also provides a Variant type that works like an union of all the Variant-compatible types.
+		Variant fooVar = 2; // fooVar is dynamically an integer (stored as a `long` in the Variant type).
+		fooVar = "Now fooVar is a string!";
+		fooVar = new RefCounted(); // fooVar is a GodotObject.
 		[/csharp]
 		[/codeblocks]
 		Godot tracks all scripting API variables within Variants. Without even realizing it, you use Variants all the time. When a particular language enforces its own rules for keeping data typed, then that language is applying its own custom logic over the base Variant scripting API.
 		- GDScript automatically wrap values in them. It keeps all data in plain Variants by default and then optionally enforces custom static typing rules on variable types.
-		- C# is statically typed, but uses the Mono [code]object[/code] type in place of Godot's Variant class when it needs to represent a dynamic value. [code]object[/code] is the Mono runtime's equivalent of the same concept.
+		- C# is statically typed, but uses its own implementation of the [code]Variant[/code] type in place of Godot's Variant class when it needs to represent a dynamic value. A [code]Variant[/code] can be assigned any compatible type implicitly but converting requires an explicit cast.
 		The global [method @GlobalScope.typeof] function returns the enumerated value of the Variant type stored in the current variable (see [enum Variant.Type]).
 		[codeblocks]
 		[gdscript]
@@ -42,14 +47,20 @@
 		        # Open your project.godot file to see it up close.
 		[/gdscript]
 		[csharp]
-		int foo = 2;
-		if (foo == null)
+		Variant foo = 2;
+		switch (foo.VariantType)
 		{
-		    GD.Print("foo is null");
-		}
-		if (foo is int)
-		{
-		    GD.Print("foo is an integer");
+		    case Variant.Type.Nil:
+		        GD.Print("foo is null");
+		        break;
+		    case Variant.Type.Int:
+		        GD.Print("foo is an integer");
+		        break;
+		    case Variant.Type.Object:
+		        // Note that Objects are their own special category.
+		        // You can convert a Variant to a GodotObject and use reflection to get its name.
+		        GD.Print($"foo is a(n) {foo.AsGodotObject().GetType().Name}");
+		        break;
 		}
 		[/csharp]
 		[/codeblocks]