Changes and fixes from review

Author: 31

tutorials/scripting/c_sharp/c_sharp_variant.rst

@@ -9,62 +9,63 @@ For a detailed explanation of Variant in general, see the :ref:`Variant <class_V
 We recommend avoiding ``Godot.Variant`` unless it is necessary to interact with untyped engine APIs.
 Take advantage of C#'s type safety when possible.
 
-Converting from a supported type to ``Godot.Variant`` can be done using implicit conversions. Also
-available are ``CreateFrom`` method overloads and the generic ``Variant.From<T>`` methods.
+Converting from a Variant-compatible C# type to ``Godot.Variant`` can be done using implicit
+conversions. Also available are ``CreateFrom`` method overloads and the generic ``Variant.From<T>``
+methods. Only the syntax is different: the behavior is the same.
 
 .. code-block:: csharp
 
     int x = 42;
-    Godot.Variant number = x;
-    Godot.Variant hello = "Hello, World!";
+    Variant numberVariant = x;
+    Variant helloVariant = "Hello, World!";
 
-    Godot.Variant number2 = Godot.Variant.CreateFrom(x);
-    Godot.Variant number3 = Godot.Variant.From(x);
+    Variant numberVariant2 = Variant.CreateFrom(x);
+    Variant numberVariant3 = Variant.From(x);
 
 Implicit conversions to ``Godot.Variant`` make passing variants as method arguments very convenient.
-For example, ``final_val`` of :ref:`tween_property<class_Tween_method_tween_property>`.
+For example, the third argument of :ref:`tween_property<class_Tween_method_tween_property>`
+specifying the final color of the tween is a ``Godot.Variant``.
 
 .. code-block:: csharp
 
     Tween tween = CreateTween();
     tween.TweenProperty(GetNode("Sprite"), "modulate", Colors.Red, 1.0f);
 
-Converting from ``Godot.Variant`` to a supported type can be done using explicit conversions. Also
-available are ``Variant.As{TYPE}`` methods or the generic ``Variant.As<T>`` method.
+Converting from ``Godot.Variant`` to a C# type can be done using explicit conversions. Also
+available are ``Variant.As{TYPE}`` methods or the generic ``Variant.As<T>`` method. All of these
+behave the same.
 
 .. code-block:: csharp
 
-    int cSharpNumber = (int)number;
-    string cSharpHello = (string)hello;
+    int number = (int)numberVariant;
+    string hello = (string)helloVariant;
 
-    int cSharpNumber2 = number.As<int>();
-    string cSharpHello2 = hello.AsString();
+    int number2 = numberVariant.As<int>();
+    int number3 = numberVariant.AsInt32();
 
 .. note::
 
-    All methods of converting from ``Godot.Variant`` to a C# type behave the same way. If conversion
-    is not possible, the default value of the target type or an empty array is returned. An
-    exception is not thrown.
+    The ``Variant.As{TYPE}`` methods are typically named after C# types (``Int32``), not C# keywords
+    (``int``).
 
-A matching type is not necessary for a conversion to succeed. For example, all variants are
-convertible to ``string``.
+If the Variant type doesn't match the conversion target type, the consequences vary depending on the
+source and target values.
 
-.. code-block:: csharp
-
-    string s = Variant.From(new Vector3(1, 3, 9)).As<string>();
-    GD.Print(s); // (1, 3, 9)
+- The conversion may examine the value and return a similar but potentially unexpected value of the
+  target type. For example, the string ``"42a"`` may be converted to the integer ``42``.
+- The default value of the target type may be returned.
+- An empty array may be returned.
+- An exception may be thrown.
 
-Some C# types are not directly represented by ``Variant.Type``. The ``Variant.As{TYPE}`` method uses
-a more specific name to represent them.
-
-.. code-block:: csharp
+Converting to the correct type avoids complicated behavior and should be preferred.
 
-    int cSharpNumber3 = number.AsInt32();
+The ``Variant.Obj`` property returns a C# ``object`` with the correct value for any variant. This
+may be useful when the type of Variant is completely unknown. However, when possible, prefer more
+specific conversions. ``Variant.Obj`` evaluates a ``switch`` on ``Variant.VariantType`` and it may
+not be necessary. Also, if the result is a value type, it may be boxed when it normally wouldn't be.
 
-To convert ``Godot.Variant`` to a C# ``object`` without specifying a more specific target type, use
-the ``Variant.Obj`` property. This can be used to compare two variants that both have unknown types
-using the equality operator ``==``. When possible, prefer more specific conversions. ``Variant.Obj``
-may result in unnecessary boxing of value types.
+For example, if the potential for ``Variant.As<MyNode>()`` to throw a invalid cast exception isn't
+acceptable, consider using a ``Variant.As<GodotObject>() is MyNode n`` type pattern instead.
 
 .. note::