Merge pull request #51079 from raulsntos/csharp-docs

Add documentation to GodotSharp, Fix PackedInt64Array typo

modules/mono/editor/bindings_generator.cpp

@@ -387,7 +387,7 @@ String BindingsGenerator::bbcode_to_xml(const String &p_bbcode, const TypeInterf
 					xml_output.append(link_target);
 					xml_output.append("</c>");
 				}
-			} else if (link_tag == "const") {
+			} else if (link_tag == "constant") {
 				if (!target_itype || !target_itype->is_object_type) {
 					if (OS::get_singleton()->is_stdout_verbose()) {
 						if (target_itype) {

modules/mono/editor/bindings_generator.h

@@ -575,7 +575,7 @@ class BindingsGenerator {
 
 			StaticCString::create(_STR(PackedByteArray)),
 			StaticCString::create(_STR(PackedInt32Array)),
-			StaticCString::create(_STR(PackedInt64rray)),
+			StaticCString::create(_STR(PackedInt64Array)),
 			StaticCString::create(_STR(PackedFloat32Array)),
 			StaticCString::create(_STR(PackedFloat64Array)),
 			StaticCString::create(_STR(PackedStringArray)),

modules/mono/glue/GodotSharp/GodotSharp/Core/Array.cs

@@ -93,7 +93,7 @@ internal IntPtr GetPtr()
         /// <summary>
         /// Duplicates this <see cref="Array"/>.
         /// </summary>
-        /// <param name="deep">If true, performs a deep copy.</param>
+        /// <param name="deep">If <see langword="true"/>, performs a deep copy.</param>
         /// <returns>A new Godot Array.</returns>
         public Array Duplicate(bool deep = false)
         {
@@ -155,9 +155,9 @@ public void Dispose()
         bool IList.IsFixedSize => false;
 
         /// <summary>
-        /// Returns the object at the given index.
+        /// Returns the object at the given <paramref name="index"/>.
         /// </summary>
-        /// <value>The object at the given index.</value>
+        /// <value>The object at the given <paramref name="index"/>.</value>
         public object this[int index]
         {
             get => godot_icall_Array_At(GetPtr(), index);
@@ -166,7 +166,7 @@ public object this[int index]
 
         /// <summary>
         /// Adds an object to the end of this <see cref="Array"/>.
-        /// This is the same as `append` or `push_back` in GDScript.
+        /// This is the same as <c>append</c> or <c>push_back</c> in GDScript.
         /// </summary>
         /// <param name="value">The object to add.</param>
         /// <returns>The new size after adding the object.</returns>
@@ -203,7 +203,7 @@ public object this[int index]
         public void Insert(int index, object value) => godot_icall_Array_Insert(GetPtr(), index, value);
 
         /// <summary>
-        /// Removes the first occurrence of the specified value
+        /// Removes the first occurrence of the specified <paramref name="value"/>
         /// from this <see cref="Array"/>.
         /// </summary>
         /// <param name="value">The value to remove.</param>
@@ -425,7 +425,7 @@ public static explicit operator Array(Array<T> from)
         /// <summary>
         /// Duplicates this <see cref="Array{T}"/>.
         /// </summary>
-        /// <param name="deep">If true, performs a deep copy.</param>
+        /// <param name="deep">If <see langword="true"/>, performs a deep copy.</param>
         /// <returns>A new Godot Array.</returns>
         public Array<T> Duplicate(bool deep = false)
         {
@@ -464,9 +464,9 @@ public void Shuffle()
         // IList<T>
 
         /// <summary>
-        /// Returns the value at the given index.
+        /// Returns the value at the given <paramref name="index"/>.
         /// </summary>
-        /// <value>The value at the given index.</value>
+        /// <value>The value at the given <paramref name="index"/>.</value>
         public T this[int index]
         {
             get { return (T)Array.godot_icall_Array_At_Generic(GetPtr(), index, elemTypeEncoding, elemTypeClass); }
@@ -522,7 +522,7 @@ public int Count
 
         /// <summary>
         /// Adds an item to the end of this <see cref="Array{T}"/>.
-        /// This is the same as `append` or `push_back` in GDScript.
+        /// This is the same as <c>append</c> or <c>push_back</c> in GDScript.
         /// </summary>
         /// <param name="item">The item to add.</param>
         /// <returns>The new size after adding the item.</returns>
@@ -583,7 +583,7 @@ public void CopyTo(T[] array, int arrayIndex)
         /// from this <see cref="Array{T}"/>.
         /// </summary>
         /// <param name="item">The value to remove.</param>
-        /// <returns>A bool indicating success or failure.</returns>
+        /// <returns>A <see langword="bool"/> indicating success or failure.</returns>
         public bool Remove(T item)
         {
             return Array.godot_icall_Array_Remove(GetPtr(), item);

modules/mono/glue/GodotSharp/GodotSharp/Core/Attributes/DisableGodotGeneratorsAttribute.cs

@@ -3,7 +3,5 @@
 namespace Godot
 {
     [AttributeUsage(AttributeTargets.Class)]
-    public class DisableGodotGeneratorsAttribute : Attribute
-    {
-    }
+    public class DisableGodotGeneratorsAttribute : Attribute { }
 }

modules/mono/glue/GodotSharp/GodotSharp/Core/Attributes/RPCAttributes.cs

@@ -3,8 +3,8 @@
 namespace Godot
 {
     [AttributeUsage(AttributeTargets.Method)]
-    public class RemoteAttribute : Attribute {}
+    public class RemoteAttribute : Attribute { }
 
     [AttributeUsage(AttributeTargets.Method)]
-    public class PuppetAttribute : Attribute {}
+    public class PuppetAttribute : Attribute { }
 }

modules/mono/glue/GodotSharp/GodotSharp/Core/Attributes/SignalAttribute.cs

@@ -3,7 +3,5 @@
 namespace Godot
 {
     [AttributeUsage(AttributeTargets.Delegate | AttributeTargets.Event)]
-    public class SignalAttribute : Attribute
-    {
-    }
+    public class SignalAttribute : Attribute { }
 }

modules/mono/glue/GodotSharp/GodotSharp/Core/Attributes/ToolAttribute.cs

@@ -3,5 +3,5 @@
 namespace Godot
 {
     [AttributeUsage(AttributeTargets.Class)]
-    public class ToolAttribute : Attribute {}
+    public class ToolAttribute : Attribute { }
 }

modules/mono/glue/GodotSharp/GodotSharp/Core/Basis.cs

@@ -31,7 +31,7 @@ public struct Basis : IEquatable<Basis>
         /// <summary>
         /// The basis matrix's X vector (column 0).
         /// </summary>
-        /// <value>Equivalent to <see cref="Column0"/> and array index `[0]`.</value>
+        /// <value>Equivalent to <see cref="Column0"/> and array index <c>[0]</c>.</value>
         public Vector3 x
         {
             get => Column0;
@@ -41,7 +41,7 @@ public Vector3 x
         /// <summary>
         /// The basis matrix's Y vector (column 1).
         /// </summary>
-        /// <value>Equivalent to <see cref="Column1"/> and array index `[1]`.</value>
+        /// <value>Equivalent to <see cref="Column1"/> and array index <c>[1]</c>.</value>
         public Vector3 y
         {
             get => Column1;
@@ -51,7 +51,7 @@ public Vector3 y
         /// <summary>
         /// The basis matrix's Z vector (column 2).
         /// </summary>
-        /// <value>Equivalent to <see cref="Column2"/> and array index `[2]`.</value>
+        /// <value>Equivalent to <see cref="Column2"/> and array index <c>[2]</c>.</value>
         public Vector3 z
         {
             get => Column2;
@@ -82,7 +82,7 @@ public Vector3 z
         /// <summary>
         /// Column 0 of the basis matrix (the X vector).
         /// </summary>
-        /// <value>Equivalent to <see cref="x"/> and array index `[0]`.</value>
+        /// <value>Equivalent to <see cref="x"/> and array index <c>[0]</c>.</value>
         public Vector3 Column0
         {
             get => new Vector3(Row0.x, Row1.x, Row2.x);
@@ -97,7 +97,7 @@ public Vector3 Column0
         /// <summary>
         /// Column 1 of the basis matrix (the Y vector).
         /// </summary>
-        /// <value>Equivalent to <see cref="y"/> and array index `[1]`.</value>
+        /// <value>Equivalent to <see cref="y"/> and array index <c>[1]</c>.</value>
         public Vector3 Column1
         {
             get => new Vector3(Row0.y, Row1.y, Row2.y);
@@ -112,7 +112,7 @@ public Vector3 Column1
         /// <summary>
         /// Column 2 of the basis matrix (the Z vector).
         /// </summary>
-        /// <value>Equivalent to <see cref="z"/> and array index `[2]`.</value>
+        /// <value>Equivalent to <see cref="z"/> and array index <c>[2]</c>.</value>
         public Vector3 Column2
         {
             get => new Vector3(Row0.z, Row1.z, Row2.z);
@@ -150,9 +150,10 @@ public Vector3 Scale
         }
 
         /// <summary>
-        /// Access whole columns in the form of Vector3.
+        /// Access whole columns in the form of <see cref="Vector3"/>.
         /// </summary>
         /// <param name="column">Which column vector.</param>
+        /// <value>The basis column.</value>
         public Vector3 this[int column]
         {
             get
@@ -193,6 +194,7 @@ public Vector3 this[int column]
         /// </summary>
         /// <param name="column">Which column, the matrix horizontal position.</param>
         /// <param name="row">Which row, the matrix vertical position.</param>
+        /// <value>The matrix element.</value>
         public real_t this[int column, int row]
         {
             get
@@ -207,6 +209,13 @@ public Vector3 this[int column]
             }
         }
 
+        /// <summary>
+        /// Returns the <see cref="Basis"/>'s rotation in the form of a
+        /// <see cref="Quaternion"/>. See <see cref="GetEuler"/> if you
+        /// need Euler angles, but keep in mind quaternions should generally
+        /// be preferred to Euler angles.
+        /// </summary>
+        /// <returns>The basis rotation.</returns>
         public Quaternion GetRotationQuaternion()
         {
             Basis orthonormalizedBasis = Orthonormalized();
@@ -263,10 +272,10 @@ public real_t Determinant()
         /// The returned vector contains the rotation angles in
         /// the format (X angle, Y angle, Z angle).
         ///
-        /// Consider using the <see cref="Basis.Quaternion()"/> method instead, which
+        /// Consider using the <see cref="Quaternion()"/> method instead, which
         /// returns a <see cref="Godot.Quaternion"/> quaternion instead of Euler angles.
         /// </summary>
-        /// <returns>A Vector3 representing the basis rotation in Euler angles.</returns>
+        /// <returns>A <see cref="Vector3"/> representing the basis rotation in Euler angles.</returns>
         public Vector3 GetEuler()
         {
             Basis m = Orthonormalized();
@@ -304,7 +313,10 @@ public Vector3 GetEuler()
         /// but are more efficient for some internal calculations.
         /// </summary>
         /// <param name="index">Which row.</param>
-        /// <returns>One of `Row0`, `Row1`, or `Row2`.</returns>
+        /// <exception cref="IndexOutOfRangeException">
+        /// Thrown when the <paramref name="index"/> is not 0, 1 or 2.
+        /// </exception>
+        /// <returns>One of <c>Row0</c>, <c>Row1</c>, or <c>Row2</c>.</returns>
         public Vector3 GetRow(int index)
         {
             switch (index)
@@ -326,6 +338,9 @@ public Vector3 GetRow(int index)
         /// </summary>
         /// <param name="index">Which row.</param>
         /// <param name="value">The vector to set the row to.</param>
+        /// <exception cref="IndexOutOfRangeException">
+        /// Thrown when the <paramref name="index"/> is not 0, 1 or 2.
+        /// </exception>
         public void SetRow(int index, Vector3 value)
         {
             switch (index)
@@ -452,8 +467,8 @@ public Basis Orthonormalized()
         }
 
         /// <summary>
-        /// Introduce an additional rotation around the given `axis`
-        /// by `phi` (in radians). The axis must be a normalized vector.
+        /// Introduce an additional rotation around the given <paramref name="axis"/>
+        /// by <paramref name="phi"/> (in radians). The axis must be a normalized vector.
         /// </summary>
         /// <param name="axis">The axis to rotate around. Must be normalized.</param>
         /// <param name="phi">The angle to rotate, in radians.</param>
@@ -553,6 +568,7 @@ public Basis Transposed()
         /// <summary>
         /// Returns a vector transformed (multiplied) by the basis matrix.
         /// </summary>
+        /// <seealso cref="XformInv(Vector3)"/>
         /// <param name="v">A vector to transform.</param>
         /// <returns>The transformed vector.</returns>
         public Vector3 Xform(Vector3 v)
@@ -571,6 +587,7 @@ public Vector3 Xform(Vector3 v)
         /// Note: This results in a multiplication by the inverse of the
         /// basis matrix only if it represents a rotation-reflection.
         /// </summary>
+        /// <seealso cref="Xform(Vector3)"/>
         /// <param name="v">A vector to inversely transform.</param>
         /// <returns>The inversely transformed vector.</returns>
         public Vector3 XformInv(Vector3 v)
@@ -675,25 +692,25 @@ public Quaternion Quaternion()
 
         /// <summary>
         /// The identity basis, with no rotation or scaling applied.
-        /// This is used as a replacement for `Basis()` in GDScript.
-        /// Do not use `new Basis()` with no arguments in C#, because it sets all values to zero.
+        /// This is used as a replacement for <c>Basis()</c> in GDScript.
+        /// Do not use <c>new Basis()</c> with no arguments in C#, because it sets all values to zero.
         /// </summary>
-        /// <value>Equivalent to `new Basis(Vector3.Right, Vector3.Up, Vector3.Back)`.</value>
+        /// <value>Equivalent to <c>new Basis(Vector3.Right, Vector3.Up, Vector3.Back)</c>.</value>
         public static Basis Identity { get { return _identity; } }
         /// <summary>
         /// The basis that will flip something along the X axis when used in a transformation.
         /// </summary>
-        /// <value>Equivalent to `new Basis(Vector3.Left, Vector3.Up, Vector3.Back)`.</value>
+        /// <value>Equivalent to <c>new Basis(Vector3.Left, Vector3.Up, Vector3.Back)</c>.</value>
         public static Basis FlipX { get { return _flipX; } }
         /// <summary>
         /// The basis that will flip something along the Y axis when used in a transformation.
         /// </summary>
-        /// <value>Equivalent to `new Basis(Vector3.Right, Vector3.Down, Vector3.Back)`.</value>
+        /// <value>Equivalent to <c>new Basis(Vector3.Right, Vector3.Down, Vector3.Back)</c>.</value>
         public static Basis FlipY { get { return _flipY; } }
         /// <summary>
         /// The basis that will flip something along the Z axis when used in a transformation.
         /// </summary>
-        /// <value>Equivalent to `new Basis(Vector3.Right, Vector3.Up, Vector3.Forward)`.</value>
+        /// <value>Equivalent to <c>new Basis(Vector3.Right, Vector3.Up, Vector3.Forward)</c>.</value>
         public static Basis FlipZ { get { return _flipZ; } }
 
         /// <summary>
@@ -752,8 +769,8 @@ public Basis(Vector3 eulerYXZ)
         }
 
         /// <summary>
-        /// Constructs a pure rotation basis matrix, rotated around the given `axis`
-        /// by `phi` (in radians). The axis must be a normalized vector.
+        /// Constructs a pure rotation basis matrix, rotated around the given <paramref name="axis"/>
+        /// by <paramref name="phi"/> (in radians). The axis must be a normalized vector.
         /// </summary>
         /// <param name="axis">The axis to rotate around. Must be normalized.</param>
         /// <param name="phi">The angle to rotate, in radians.</param>
@@ -830,6 +847,11 @@ internal Basis(real_t xx, real_t yx, real_t zx, real_t xy, real_t yy, real_t zy,
             return !left.Equals(right);
         }
 
+        /// <summary>
+        /// Returns <see langword="true"/> if this basis and <paramref name="obj"/> are equal.
+        /// </summary>
+        /// <param name="obj">The other object to compare.</param>
+        /// <returns>Whether or not the basis and the other object are equal.</returns>
         public override bool Equals(object obj)
         {
             if (obj is Basis)
@@ -840,32 +862,49 @@ public override bool Equals(object obj)
             return false;
         }
 
+        /// <summary>
+        /// Returns <see langword="true"/> if this basis and <paramref name="other"/> are equal
+        /// </summary>
+        /// <param name="other">The other basis to compare.</param>
+        /// <returns>Whether or not the bases are equal.</returns>
         public bool Equals(Basis other)
         {
             return Row0.Equals(other.Row0) && Row1.Equals(other.Row1) && Row2.Equals(other.Row2);
         }
 
         /// <summary>
-        /// Returns true if this basis and `other` are approximately equal, by running
-        /// <see cref="Vector3.IsEqualApprox(Vector3)"/> on each component.
+        /// Returns <see langword="true"/> if this basis and <paramref name="other"/> are approximately equal,
+        /// by running <see cref="Vector3.IsEqualApprox(Vector3)"/> on each component.
         /// </summary>
         /// <param name="other">The other basis to compare.</param>
-        /// <returns>Whether or not the matrices are approximately equal.</returns>
+        /// <returns>Whether or not the bases are approximately equal.</returns>
         public bool IsEqualApprox(Basis other)
         {
             return Row0.IsEqualApprox(other.Row0) && Row1.IsEqualApprox(other.Row1) && Row2.IsEqualApprox(other.Row2);
         }
 
+        /// <summary>
+        /// Serves as the hash function for <see cref="Basis"/>.
+        /// </summary>
+        /// <returns>A hash code for this basis.</returns>
         public override int GetHashCode()
         {
             return Row0.GetHashCode() ^ Row1.GetHashCode() ^ Row2.GetHashCode();
         }
 
+        /// <summary>
+        /// Converts this <see cref="Basis"/> to a string.
+        /// </summary>
+        /// <returns>A string representation of this basis.</returns>
         public override string ToString()
         {
             return $"[X: {x}, Y: {y}, Z: {z}]";
         }
 
+        /// <summary>
+        /// Converts this <see cref="Basis"/> to a string with the given <paramref name="format"/>.
+        /// </summary>
+        /// <returns>A string representation of this basis.</returns>
         public string ToString(string format)
         {
             return $"[X: {x.ToString(format)}, Y: {y.ToString(format)}, Z: {z.ToString(format)}]";