From d76562ceb98a8f0d45c3e53bffaeea749469edea Mon Sep 17 00:00:00 2001 From: Raul Santos Date: Wed, 4 Aug 2021 21:17:16 +0200 Subject: [PATCH 1/2] Fix constant tag documentation in C# bindings generator --- modules/mono/editor/bindings_generator.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/mono/editor/bindings_generator.cpp b/modules/mono/editor/bindings_generator.cpp index c9acd5cec6b..07fb0cdd996 100644 --- a/modules/mono/editor/bindings_generator.cpp +++ b/modules/mono/editor/bindings_generator.cpp @@ -376,7 +376,7 @@ String BindingsGenerator::bbcode_to_xml(const String &p_bbcode, const TypeInterf xml_output.append(link_target); xml_output.append(""); } - } 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) { From cacf3e28fd3d6df74578449eb8a18c3f58956fb4 Mon Sep 17 00:00:00 2001 From: Raul Santos Date: Fri, 3 Sep 2021 02:00:47 +0200 Subject: [PATCH 2/2] Add documentation to GodotSharp - Adds documentation to almost every class and member in `GodotSharp` - Fixes some old documentation to more closely follow the XML comments convention --- .../glue/GodotSharp/GodotSharp/Core/AABB.cs | 156 +++++--- .../glue/GodotSharp/GodotSharp/Core/Array.cs | 20 +- .../Core/Attributes/RPCAttributes.cs | 16 +- .../Core/Attributes/SignalAttribute.cs | 4 +- .../Core/Attributes/ToolAttribute.cs | 2 +- .../glue/GodotSharp/GodotSharp/Core/Basis.cs | 83 ++-- .../glue/GodotSharp/GodotSharp/Core/Color.cs | 84 ++-- .../GodotSharp/Core/DynamicObject.cs | 30 +- .../Core/Extensions/NodeExtensions.cs | 150 +++++++ .../Core/Extensions/ObjectExtensions.cs | 22 +- .../Core/Extensions/PackedSceneExtensions.cs | 19 +- .../Extensions/ResourceLoaderExtensions.cs | 20 + .../glue/GodotSharp/GodotSharp/Core/GD.cs | 357 ++++++++++++++++- .../GodotSharp/Core/MarshalUtils.cs | 121 ++++-- .../glue/GodotSharp/GodotSharp/Core/Mathf.cs | 167 ++++---- .../GodotSharp/GodotSharp/Core/MathfEx.cs | 29 +- .../GodotSharp/GodotSharp/Core/NodePath.cs | 156 +++++++- .../GodotSharp/GodotSharp/Core/Object.base.cs | 24 +- .../glue/GodotSharp/GodotSharp/Core/Plane.cs | 92 +++-- .../glue/GodotSharp/GodotSharp/Core/Quat.cs | 91 +++-- .../glue/GodotSharp/GodotSharp/Core/RID.cs | 25 +- .../glue/GodotSharp/GodotSharp/Core/Rect2.cs | 126 ++++-- .../GodotSharp/Core/StringExtensions.cs | 369 ++++++++++++++++-- .../GodotSharp/GodotSharp/Core/Transform.cs | 73 ++-- .../GodotSharp/GodotSharp/Core/Transform2D.cs | 90 +++-- .../GodotSharp/Core/UnhandledExceptionArgs.cs | 2 +- .../GodotSharp/GodotSharp/Core/Vector2.cs | 141 ++++--- .../GodotSharp/GodotSharp/Core/Vector3.cs | 151 ++++--- 28 files changed, 2060 insertions(+), 560 deletions(-) diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/AABB.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/AABB.cs index 4c3d4e2cca9..fd056a06ebc 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/AABB.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/AABB.cs @@ -20,7 +20,7 @@ namespace Godot private Vector3 _size; /// - /// Beginning corner. Typically has values lower than End. + /// Beginning corner. Typically has values lower than . /// /// Directly uses a private field. public Vector3 Position @@ -30,7 +30,7 @@ namespace Godot } /// - /// Size from Position to End. Typically all components are positive. + /// Size from to . Typically all components are positive. /// If the size is negative, you can use to fix it. /// /// Directly uses a private field. @@ -44,7 +44,10 @@ namespace Godot /// Ending corner. This is calculated as plus /// . Setting this value will change the size. /// - /// Getting is equivalent to `value = Position + Size`, setting is equivalent to `Size = value - Position`. + /// + /// Getting is equivalent to = + , + /// setting is equivalent to = - + /// public Vector3 End { get { return _position + _size; } @@ -52,10 +55,10 @@ namespace Godot } /// - /// Returns an AABB with equivalent position and size, modified so that + /// Returns an with equivalent position and size, modified so that /// the most-negative corner is the origin and the size is positive. /// - /// The modified AABB. + /// The modified . public AABB Abs() { Vector3 end = End; @@ -64,10 +67,12 @@ namespace Godot } /// - /// Returns true if this AABB completely encloses another one. + /// Returns if this completely encloses another one. /// - /// The other AABB that may be enclosed. - /// A bool for whether or not this AABB encloses `b`. + /// The other that may be enclosed. + /// + /// A for whether or not this encloses . + /// public bool Encloses(AABB with) { Vector3 src_min = _position; @@ -84,10 +89,10 @@ namespace Godot } /// - /// Returns this AABB expanded to include a given point. + /// Returns this expanded to include a given point. /// /// The point to include. - /// The expanded AABB. + /// The expanded . public AABB Expand(Vector3 point) { Vector3 begin = _position; @@ -123,7 +128,7 @@ namespace Godot } /// - /// Returns the area of the AABB. + /// Returns the area of the . /// /// The area. public real_t GetArea() @@ -132,10 +137,10 @@ namespace Godot } /// - /// Gets the position of one of the 8 endpoints of the AABB. + /// Gets the position of one of the 8 endpoints of the . /// /// Which endpoint to get. - /// An endpoint of the AABB. + /// An endpoint of the . public Vector3 GetEndpoint(int idx) { switch (idx) @@ -162,9 +167,9 @@ namespace Godot } /// - /// Returns the normalized longest axis of the AABB. + /// Returns the normalized longest axis of the . /// - /// A vector representing the normalized longest axis of the AABB. + /// A vector representing the normalized longest axis of the . public Vector3 GetLongestAxis() { var axis = new Vector3(1f, 0f, 0f); @@ -185,7 +190,7 @@ namespace Godot } /// - /// Returns the index of the longest axis of the AABB. + /// Returns the index of the longest axis of the . /// /// A index for which axis is longest. public Vector3.Axis GetLongestAxisIndex() @@ -208,9 +213,9 @@ namespace Godot } /// - /// Returns the scalar length of the longest axis of the AABB. + /// Returns the scalar length of the longest axis of the . /// - /// The scalar length of the longest axis of the AABB. + /// The scalar length of the longest axis of the . public real_t GetLongestAxisSize() { real_t max_size = _size.x; @@ -225,9 +230,9 @@ namespace Godot } /// - /// Returns the normalized shortest axis of the AABB. + /// Returns the normalized shortest axis of the . /// - /// A vector representing the normalized shortest axis of the AABB. + /// A vector representing the normalized shortest axis of the . public Vector3 GetShortestAxis() { var axis = new Vector3(1f, 0f, 0f); @@ -248,7 +253,7 @@ namespace Godot } /// - /// Returns the index of the shortest axis of the AABB. + /// Returns the index of the shortest axis of the . /// /// A index for which axis is shortest. public Vector3.Axis GetShortestAxisIndex() @@ -271,9 +276,9 @@ namespace Godot } /// - /// Returns the scalar length of the shortest axis of the AABB. + /// Returns the scalar length of the shortest axis of the . /// - /// The scalar length of the shortest axis of the AABB. + /// The scalar length of the shortest axis of the . public real_t GetShortestAxisSize() { real_t max_size = _size.x; @@ -305,10 +310,10 @@ namespace Godot } /// - /// Returns a copy of the AABB grown a given amount of units towards all the sides. + /// Returns a copy of the grown a given amount of units towards all the sides. /// /// The amount to grow by. - /// The grown AABB. + /// The grown . public AABB Grow(real_t by) { var res = this; @@ -324,28 +329,37 @@ namespace Godot } /// - /// Returns true if the AABB is flat or empty, or false otherwise. + /// Returns if the is flat or empty, + /// or otherwise. /// - /// A bool for whether or not the AABB has area. + /// + /// A for whether or not the has area. + /// public bool HasNoArea() { return _size.x <= 0f || _size.y <= 0f || _size.z <= 0f; } /// - /// Returns true if the AABB has no surface (no size), or false otherwise. + /// Returns if the has no surface (no size), + /// or otherwise. /// - /// A bool for whether or not the AABB has area. + /// + /// A for whether or not the has area. + /// public bool HasNoSurface() { return _size.x <= 0f && _size.y <= 0f && _size.z <= 0f; } /// - /// Returns true if the AABB contains a point, or false otherwise. + /// Returns if the contains a point, + /// or otherwise. /// /// The point to check. - /// A bool for whether or not the AABB contains `point`. + /// + /// A for whether or not the contains . + /// public bool HasPoint(Vector3 point) { if (point.x < _position.x) @@ -365,10 +379,10 @@ namespace Godot } /// - /// Returns the intersection of this AABB and `b`. + /// Returns the intersection of this and . /// - /// The other AABB. - /// The clipped AABB. + /// The other . + /// The clipped . public AABB Intersection(AABB with) { Vector3 src_min = _position; @@ -406,15 +420,18 @@ namespace Godot } /// - /// Returns true if the AABB overlaps with `b` + /// Returns if the overlaps with /// (i.e. they have at least one point in common). /// - /// If `includeBorders` is true, they will also be considered overlapping - /// if their borders touch, even without intersection. + /// If is , + /// they will also be considered overlapping if their borders touch, + /// even without intersection. /// - /// The other AABB to check for intersections with. + /// The other to check for intersections with. /// Whether or not to consider borders. - /// A bool for whether or not they are intersecting. + /// + /// A for whether or not they are intersecting. + /// public bool Intersects(AABB with, bool includeBorders = false) { if (includeBorders) @@ -452,10 +469,12 @@ namespace Godot } /// - /// Returns true if the AABB is on both sides of `plane`. + /// Returns if the is on both sides of . /// - /// The plane to check for intersection. - /// A bool for whether or not the AABB intersects the plane. + /// The to check for intersection. + /// + /// A for whether or not the intersects the . + /// public bool IntersectsPlane(Plane plane) { Vector3[] points = @@ -489,11 +508,14 @@ namespace Godot } /// - /// Returns true if the AABB intersects the line segment between `from` and `to`. + /// Returns if the intersects + /// the line segment between and . /// /// The start of the line segment. /// The end of the line segment. - /// A bool for whether or not the AABB intersects the line segment. + /// + /// A for whether or not the intersects the line segment. + /// public bool IntersectsSegment(Vector3 from, Vector3 to) { real_t min = 0f; @@ -549,10 +571,10 @@ namespace Godot } /// - /// Returns a larger AABB that contains this AABB and `b`. + /// Returns a larger that contains this and . /// - /// The other AABB. - /// The merged AABB. + /// The other . + /// The merged . public AABB Merge(AABB with) { Vector3 beg1 = _position; @@ -576,7 +598,7 @@ namespace Godot } /// - /// Constructs an AABB from a position and size. + /// Constructs an from a position and size. /// /// The position. /// The size, typically positive. @@ -587,7 +609,8 @@ namespace Godot } /// - /// Constructs an AABB from a position, width, height, and depth. + /// Constructs an from a , + /// , , and . /// /// The position. /// The width, typically positive. @@ -600,7 +623,8 @@ namespace Godot } /// - /// Constructs an AABB from x, y, z, and size. + /// Constructs an from , + /// , , and . /// /// The position's X coordinate. /// The position's Y coordinate. @@ -613,7 +637,9 @@ namespace Godot } /// - /// Constructs an AABB from x, y, z, width, height, and depth. + /// Constructs an from , + /// , , , + /// , and . /// /// The position's X coordinate. /// The position's Y coordinate. @@ -637,6 +663,11 @@ namespace Godot return !left.Equals(right); } + /// + /// Returns if this AABB and are equal. + /// + /// The other object to compare. + /// Whether or not the AABB structure and the other object are equal. public override bool Equals(object obj) { if (obj is AABB) @@ -647,27 +678,40 @@ namespace Godot return false; } + /// + /// Returns if this AABB and are equal + /// + /// The other AABB to compare. + /// Whether or not the AABBs are equal. public bool Equals(AABB other) { return _position == other._position && _size == other._size; } /// - /// Returns true if this AABB and `other` are approximately equal, by running - /// on each component. + /// Returns if this AABB and are approximately equal, + /// by running on each component. /// /// The other AABB to compare. - /// Whether or not the AABBs are approximately equal. + /// Whether or not the AABBs structures are approximately equal. public bool IsEqualApprox(AABB other) { return _position.IsEqualApprox(other._position) && _size.IsEqualApprox(other._size); } + /// + /// Serves as the hash function for . + /// + /// A hash code for this AABB. public override int GetHashCode() { return _position.GetHashCode() ^ _size.GetHashCode(); } + /// + /// Converts this to a string. + /// + /// A string representation of this AABB. public override string ToString() { return String.Format("{0} - {1}", new object[] @@ -677,6 +721,10 @@ namespace Godot }); } + /// + /// Converts this to a string with the given . + /// + /// A string representation of this AABB. public string ToString(string format) { return String.Format("{0} - {1}", new object[] diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Array.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Array.cs index f52a767018b..b996ff9d803 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Array.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Array.cs @@ -93,7 +93,7 @@ namespace Godot.Collections /// /// Duplicates this . /// - /// If true, performs a deep copy. + /// If , performs a deep copy. /// A new Godot Array. public Array Duplicate(bool deep = false) { @@ -155,9 +155,9 @@ namespace Godot.Collections bool IList.IsFixedSize => false; /// - /// Returns the object at the given index. + /// Returns the object at the given . /// - /// The object at the given index. + /// The object at the given . public object this[int index] { get => godot_icall_Array_At(GetPtr(), index); @@ -166,7 +166,7 @@ namespace Godot.Collections /// /// Adds an object to the end of this . - /// This is the same as `append` or `push_back` in GDScript. + /// This is the same as append or push_back in GDScript. /// /// The object to add. /// The new size after adding the object. @@ -203,7 +203,7 @@ namespace Godot.Collections public void Insert(int index, object value) => godot_icall_Array_Insert(GetPtr(), index, value); /// - /// Removes the first occurrence of the specified value + /// Removes the first occurrence of the specified /// from this . /// /// The value to remove. @@ -425,7 +425,7 @@ namespace Godot.Collections /// /// Duplicates this . /// - /// If true, performs a deep copy. + /// If , performs a deep copy. /// A new Godot Array. public Array Duplicate(bool deep = false) { @@ -464,9 +464,9 @@ namespace Godot.Collections // IList /// - /// Returns the value at the given index. + /// Returns the value at the given . /// - /// The value at the given index. + /// The value at the given . public T this[int index] { get { return (T)Array.godot_icall_Array_At_Generic(GetPtr(), index, elemTypeEncoding, elemTypeClass); } @@ -522,7 +522,7 @@ namespace Godot.Collections /// /// Adds an item to the end of this . - /// This is the same as `append` or `push_back` in GDScript. + /// This is the same as append or push_back in GDScript. /// /// The item to add. /// The new size after adding the item. @@ -583,7 +583,7 @@ namespace Godot.Collections /// from this . /// /// The value to remove. - /// A bool indicating success or failure. + /// A indicating success or failure. public bool Remove(T item) { return Array.godot_icall_Array_Remove(GetPtr(), item); diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Attributes/RPCAttributes.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Attributes/RPCAttributes.cs index 1bf6d5199a3..05082663dc8 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Attributes/RPCAttributes.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Attributes/RPCAttributes.cs @@ -3,26 +3,26 @@ using System; namespace Godot { [AttributeUsage(AttributeTargets.Method | AttributeTargets.Field | AttributeTargets.Property)] - public class RemoteAttribute : Attribute {} + public class RemoteAttribute : Attribute { } [AttributeUsage(AttributeTargets.Method | AttributeTargets.Field | AttributeTargets.Property)] - public class SyncAttribute : Attribute {} + public class SyncAttribute : Attribute { } [AttributeUsage(AttributeTargets.Method | AttributeTargets.Field | AttributeTargets.Property)] - public class MasterAttribute : Attribute {} + public class MasterAttribute : Attribute { } [AttributeUsage(AttributeTargets.Method | AttributeTargets.Field | AttributeTargets.Property)] - public class PuppetAttribute : Attribute {} + public class PuppetAttribute : Attribute { } [AttributeUsage(AttributeTargets.Method | AttributeTargets.Field | AttributeTargets.Property)] - public class SlaveAttribute : Attribute {} + public class SlaveAttribute : Attribute { } [AttributeUsage(AttributeTargets.Method | AttributeTargets.Field | AttributeTargets.Property)] - public class RemoteSyncAttribute : Attribute {} + public class RemoteSyncAttribute : Attribute { } [AttributeUsage(AttributeTargets.Method | AttributeTargets.Field | AttributeTargets.Property)] - public class MasterSyncAttribute : Attribute {} + public class MasterSyncAttribute : Attribute { } [AttributeUsage(AttributeTargets.Method | AttributeTargets.Field | AttributeTargets.Property)] - public class PuppetSyncAttribute : Attribute {} + public class PuppetSyncAttribute : Attribute { } } diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Attributes/SignalAttribute.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Attributes/SignalAttribute.cs index 3957387be95..38e68a89d51 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Attributes/SignalAttribute.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Attributes/SignalAttribute.cs @@ -3,7 +3,5 @@ using System; namespace Godot { [AttributeUsage(AttributeTargets.Delegate)] - public class SignalAttribute : Attribute - { - } + public class SignalAttribute : Attribute { } } diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Attributes/ToolAttribute.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Attributes/ToolAttribute.cs index d0437409afb..d2344389f4e 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Attributes/ToolAttribute.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Attributes/ToolAttribute.cs @@ -3,5 +3,5 @@ using System; namespace Godot { [AttributeUsage(AttributeTargets.Class)] - public class ToolAttribute : Attribute {} + public class ToolAttribute : Attribute { } } diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Basis.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Basis.cs index f3b0ced10b1..6c426d7e377 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Basis.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Basis.cs @@ -31,7 +31,7 @@ namespace Godot /// /// The basis matrix's X vector (column 0). /// - /// Equivalent to and array index `[0]`. + /// Equivalent to and array index [0]. public Vector3 x { get => Column0; @@ -41,7 +41,7 @@ namespace Godot /// /// The basis matrix's Y vector (column 1). /// - /// Equivalent to and array index `[1]`. + /// Equivalent to and array index [1]. public Vector3 y { get => Column1; @@ -51,7 +51,7 @@ namespace Godot /// /// The basis matrix's Z vector (column 2). /// - /// Equivalent to and array index `[2]`. + /// Equivalent to and array index [2]. public Vector3 z { get => Column2; @@ -82,7 +82,7 @@ namespace Godot /// /// Column 0 of the basis matrix (the X vector). /// - /// Equivalent to and array index `[0]`. + /// Equivalent to and array index [0]. public Vector3 Column0 { get => new Vector3(Row0.x, Row1.x, Row2.x); @@ -97,7 +97,7 @@ namespace Godot /// /// Column 1 of the basis matrix (the Y vector). /// - /// Equivalent to and array index `[1]`. + /// Equivalent to and array index [1]. public Vector3 Column1 { get => new Vector3(Row0.y, Row1.y, Row2.y); @@ -112,7 +112,7 @@ namespace Godot /// /// Column 2 of the basis matrix (the Z vector). /// - /// Equivalent to and array index `[2]`. + /// Equivalent to and array index [2]. public Vector3 Column2 { get => new Vector3(Row0.z, Row1.z, Row2.z); @@ -150,9 +150,10 @@ namespace Godot } /// - /// Access whole columns in the form of Vector3. + /// Access whole columns in the form of . /// /// Which column vector. + /// The basis column. public Vector3 this[int column] { get @@ -193,6 +194,7 @@ namespace Godot /// /// Which column, the matrix horizontal position. /// Which row, the matrix vertical position. + /// The matrix element. public real_t this[int column, int row] { get @@ -207,6 +209,13 @@ namespace Godot } } + /// + /// Returns the 's rotation in the form of a + /// . See if you + /// need Euler angles, but keep in mind quaternions should generally + /// be preferred to Euler angles. + /// + /// The basis rotation. public Quat RotationQuat() { Basis orthonormalizedBasis = Orthonormalized(); @@ -266,7 +275,7 @@ namespace Godot /// Consider using the method instead, which /// returns a quaternion instead of Euler angles. /// - /// A Vector3 representing the basis rotation in Euler angles. + /// A representing the basis rotation in Euler angles. public Vector3 GetEuler() { Basis m = Orthonormalized(); @@ -304,7 +313,10 @@ namespace Godot /// but are more efficient for some internal calculations. /// /// Which row. - /// One of `Row0`, `Row1`, or `Row2`. + /// + /// Thrown when the is not 0, 1 or 2. + /// + /// One of Row0, Row1, or Row2. public Vector3 GetRow(int index) { switch (index) @@ -326,6 +338,9 @@ namespace Godot /// /// Which row. /// The vector to set the row to. + /// + /// Thrown when the is not 0, 1 or 2. + /// public void SetRow(int index, Vector3 value) { switch (index) @@ -485,8 +500,8 @@ namespace Godot } /// - /// 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 + /// by (in radians). The axis must be a normalized vector. /// /// The axis to rotate around. Must be normalized. /// The angle to rotate, in radians. @@ -586,6 +601,7 @@ namespace Godot /// /// Returns a vector transformed (multiplied) by the basis matrix. /// + /// /// A vector to transform. /// The transformed vector. public Vector3 Xform(Vector3 v) @@ -604,6 +620,7 @@ namespace Godot /// Note: This results in a multiplication by the inverse of the /// basis matrix only if it represents a rotation-reflection. /// + /// /// A vector to inversely transform. /// The inversely transformed vector. public Vector3 XformInv(Vector3 v) @@ -708,25 +725,25 @@ namespace Godot /// /// 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 Basis() in GDScript. + /// Do not use new Basis() with no arguments in C#, because it sets all values to zero. /// - /// Equivalent to `new Basis(Vector3.Right, Vector3.Up, Vector3.Back)`. + /// Equivalent to new Basis(Vector3.Right, Vector3.Up, Vector3.Back). public static Basis Identity { get { return _identity; } } /// /// The basis that will flip something along the X axis when used in a transformation. /// - /// Equivalent to `new Basis(Vector3.Left, Vector3.Up, Vector3.Back)`. + /// Equivalent to new Basis(Vector3.Left, Vector3.Up, Vector3.Back). public static Basis FlipX { get { return _flipX; } } /// /// The basis that will flip something along the Y axis when used in a transformation. /// - /// Equivalent to `new Basis(Vector3.Right, Vector3.Down, Vector3.Back)`. + /// Equivalent to new Basis(Vector3.Right, Vector3.Down, Vector3.Back). public static Basis FlipY { get { return _flipY; } } /// /// The basis that will flip something along the Z axis when used in a transformation. /// - /// Equivalent to `new Basis(Vector3.Right, Vector3.Up, Vector3.Forward)`. + /// Equivalent to new Basis(Vector3.Right, Vector3.Up, Vector3.Forward). public static Basis FlipZ { get { return _flipZ; } } /// @@ -785,8 +802,8 @@ namespace Godot } /// - /// 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 + /// by (in radians). The axis must be a normalized vector. /// /// The axis to rotate around. Must be normalized. /// The angle to rotate, in radians. @@ -863,6 +880,11 @@ namespace Godot return !left.Equals(right); } + /// + /// Returns if this basis and are equal. + /// + /// The other object to compare. + /// Whether or not the basis and the other object are equal. public override bool Equals(object obj) { if (obj is Basis) @@ -873,27 +895,40 @@ namespace Godot return false; } + /// + /// Returns if this basis and are equal + /// + /// The other basis to compare. + /// Whether or not the bases are equal. public bool Equals(Basis other) { return Row0.Equals(other.Row0) && Row1.Equals(other.Row1) && Row2.Equals(other.Row2); } /// - /// Returns true if this basis and `other` are approximately equal, by running - /// on each component. + /// Returns if this basis and are approximately equal, + /// by running on each component. /// /// The other basis to compare. - /// Whether or not the matrices are approximately equal. + /// Whether or not the bases are approximately equal. public bool IsEqualApprox(Basis other) { return Row0.IsEqualApprox(other.Row0) && Row1.IsEqualApprox(other.Row1) && Row2.IsEqualApprox(other.Row2); } + /// + /// Serves as the hash function for . + /// + /// A hash code for this basis. public override int GetHashCode() { return Row0.GetHashCode() ^ Row1.GetHashCode() ^ Row2.GetHashCode(); } + /// + /// Converts this to a string. + /// + /// A string representation of this basis. public override string ToString() { return String.Format("({0}, {1}, {2})", new object[] @@ -904,6 +939,10 @@ namespace Godot }); } + /// + /// Converts this to a string with the given . + /// + /// A string representation of this basis. public string ToString(string format) { return String.Format("({0}, {1}, {2})", new object[] diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Color.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Color.cs index 7732c19d900..59464f72760 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Color.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Color.cs @@ -7,11 +7,11 @@ namespace Godot /// A color represented by red, green, blue, and alpha (RGBA) components. /// The alpha component is often used for transparency. /// Values are in floating-point and usually range from 0 to 1. - /// Some properties (such as CanvasItem.modulate) may accept values + /// Some properties (such as ) may accept values /// greater than 1 (overbright or HDR colors). /// /// If you want to supply values in a range of 0 to 255, you should use - /// and the `r8`/`g8`/`b8`/`a8` properties. + /// and the r8/g8/b8/a8 properties. /// [Serializable] [StructLayout(LayoutKind.Sequential)] @@ -173,7 +173,7 @@ namespace Godot /// /// The HSV value (brightness) of this color, on the range 0 to 1. /// - /// Getting is equivalent to using `Max()` on the RGB components. Setting uses . + /// Getting is equivalent to using on the RGB components. Setting uses . public float v { get @@ -216,7 +216,12 @@ namespace Godot /// /// Access color components using their index. /// - /// `[0]` is equivalent to `.r`, `[1]` is equivalent to `.g`, `[2]` is equivalent to `.b`, `[3]` is equivalent to `.a`. + /// + /// [0] is equivalent to , + /// [1] is equivalent to , + /// [2] is equivalent to , + /// [3] is equivalent to . + /// public float this[int index] { get @@ -259,7 +264,7 @@ namespace Godot /// /// Converts a color to HSV values. This is equivalent to using each of - /// the `h`/`s`/`v` properties, but much more efficient. + /// the h/s/v properties, but much more efficient. /// /// Output parameter for the HSV hue. /// Output parameter for the HSV saturation. @@ -297,7 +302,7 @@ namespace Godot /// /// Constructs a color from an HSV profile, with values on the /// range of 0 to 1. This is equivalent to using each of - /// the `h`/`s`/`v` properties, but much more efficient. + /// the h/s/v properties, but much more efficient. /// /// The HSV hue, typically on the range of 0 to 1. /// The HSV saturation, typically on the range of 0 to 1. @@ -347,7 +352,7 @@ namespace Godot /// The second color may have a range of alpha values. /// /// The color to blend over. - /// This color blended over `over`. + /// This color blended over . public Color Blend(Color over) { Color res; @@ -397,7 +402,7 @@ namespace Godot } /// - /// Returns the inverted color: `(1 - r, 1 - g, 1 - b, a)`. + /// Returns the inverted color: (1 - r, 1 - g, 1 - b, a). /// /// The inverted color. public Color Inverted() @@ -427,7 +432,7 @@ namespace Godot /// /// Returns the result of the linear interpolation between - /// this color and `to` by amount `weight`. + /// this color and by amount . /// /// The destination color for interpolation. /// A value on the range of 0.0 to 1.0, representing the amount of interpolation. @@ -445,7 +450,7 @@ namespace Godot /// /// Returns the result of the linear interpolation between - /// this color and `to` by color amount `weight`. + /// this color and by color amount . /// /// The destination color for interpolation. /// A color with components on the range of 0.0 to 1.0, representing the amount of interpolation. @@ -466,7 +471,7 @@ namespace Godot /// format (each byte represents a color channel). /// ABGR is the reversed version of the default format. /// - /// An int representing this color in ABGR32 format. + /// A representing this color in ABGR32 format. public int ToAbgr32() { int c = (byte)Math.Round(a * 255); @@ -485,7 +490,7 @@ namespace Godot /// format (each word represents a color channel). /// ABGR is the reversed version of the default format. /// - /// An int representing this color in ABGR64 format. + /// A representing this color in ABGR64 format. public long ToAbgr64() { long c = (ushort)Math.Round(a * 65535); @@ -504,7 +509,7 @@ namespace Godot /// format (each byte represents a color channel). /// ARGB is more compatible with DirectX, but not used much in Godot. /// - /// An int representing this color in ARGB32 format. + /// A representing this color in ARGB32 format. public int ToArgb32() { int c = (byte)Math.Round(a * 255); @@ -523,7 +528,7 @@ namespace Godot /// format (each word represents a color channel). /// ARGB is more compatible with DirectX, but not used much in Godot. /// - /// A long representing this color in ARGB64 format. + /// A representing this color in ARGB64 format. public long ToArgb64() { long c = (ushort)Math.Round(a * 65535); @@ -542,7 +547,7 @@ namespace Godot /// format (each byte represents a color channel). /// RGBA is Godot's default and recommended format. /// - /// An int representing this color in RGBA32 format. + /// A representing this color in RGBA32 format. public int ToRgba32() { int c = (byte)Math.Round(r * 255); @@ -561,7 +566,7 @@ namespace Godot /// format (each word represents a color channel). /// RGBA is Godot's default and recommended format. /// - /// A long representing this color in RGBA64 format. + /// A representing this color in RGBA64 format. public long ToRgba64() { long c = (ushort)Math.Round(r * 65535); @@ -578,7 +583,9 @@ namespace Godot /// /// Returns the color's HTML hexadecimal color string in RGBA format. /// - /// Whether or not to include alpha. If false, the color is RGB instead of RGBA. + /// + /// Whether or not to include alpha. If , the color is RGB instead of RGBA. + /// /// A string for the HTML hexadecimal representation of this color. public string ToHtml(bool includeAlpha = true) { @@ -595,7 +602,7 @@ namespace Godot } /// - /// Constructs a color from RGBA values, typically on the range of 0 to 1. + /// Constructs a from RGBA values, typically on the range of 0 to 1. /// /// The color's red component, typically on the range of 0 to 1. /// The color's green component, typically on the range of 0 to 1. @@ -610,7 +617,7 @@ namespace Godot } /// - /// Constructs a color from an existing color and an alpha value. + /// Constructs a from an existing color and an alpha value. /// /// The color to construct from. Only its RGB values are used. /// The color's alpha (transparency) value, typically on the range of 0 to 1. Default: 1. @@ -623,10 +630,10 @@ namespace Godot } /// - /// Constructs a color from a 32-bit integer in RGBA format + /// Constructs a from a 32-bit integer in RGBA format /// (each byte represents a color channel). /// - /// The int representing the color. + /// The representing the color. public Color(int rgba) { a = (rgba & 0xFF) / 255.0f; @@ -639,10 +646,10 @@ namespace Godot } /// - /// Constructs a color from a 64-bit integer in RGBA format + /// Constructs a from a 64-bit integer in RGBA format /// (each word represents a color channel). /// - /// The long representing the color. + /// The representing the color. public Color(long rgba) { a = (rgba & 0xFFFF) / 65535.0f; @@ -762,9 +769,12 @@ namespace Godot } /// - /// Constructs a color from the HTML hexadecimal color string in RGBA format. + /// Constructs a from the HTML hexadecimal color string in RGBA format. /// /// A string for the HTML hexadecimal representation of this color. + /// + /// Thrown when the given color code is invalid. + /// public Color(string rgba) { if (rgba.Length == 0) @@ -936,6 +946,11 @@ namespace Godot return left.r > right.r; } + /// + /// Returns if this color and are equal. + /// + /// The other object to compare. + /// Whether or not the color and the other object are equal. public override bool Equals(object obj) { if (obj is Color) @@ -946,14 +961,19 @@ namespace Godot return false; } + /// + /// Returns if this color and are equal + /// + /// The other color to compare. + /// Whether or not the colors are equal. public bool Equals(Color other) { return r == other.r && g == other.g && b == other.b && a == other.a; } /// - /// Returns true if this color and `other` are approximately equal, by running - /// on each component. + /// Returns if this color and are approximately equal, + /// by running on each component. /// /// The other color to compare. /// Whether or not the colors are approximately equal. @@ -962,16 +982,28 @@ namespace Godot return Mathf.IsEqualApprox(r, other.r) && Mathf.IsEqualApprox(g, other.g) && Mathf.IsEqualApprox(b, other.b) && Mathf.IsEqualApprox(a, other.a); } + /// + /// Serves as the hash function for . + /// + /// A hash code for this color. public override int GetHashCode() { return r.GetHashCode() ^ g.GetHashCode() ^ b.GetHashCode() ^ a.GetHashCode(); } + /// + /// Converts this to a string. + /// + /// A string representation of this color. public override string ToString() { return String.Format("{0},{1},{2},{3}", r.ToString(), g.ToString(), b.ToString(), a.ToString()); } + /// + /// Converts this to a string with the given . + /// + /// A string representation of this color. public string ToString(string format) { return String.Format("{0},{1},{2},{3}", r.ToString(format), g.ToString(format), b.ToString(format), a.ToString(format)); diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/DynamicObject.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/DynamicObject.cs index 0fa970861db..8fbf52208f8 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/DynamicObject.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/DynamicObject.cs @@ -7,20 +7,20 @@ using System.Runtime.CompilerServices; namespace Godot { /// - /// Represents an whose members can be dynamically accessed at runtime through the Variant API. + /// Represents an whose members can be dynamically accessed at runtime through the Variant API. /// /// /// - /// The class enables access to the Variant - /// members of a instance at runtime. + /// The class enables access to the Variant + /// members of a instance at runtime. /// /// /// This allows accessing the class members using their original names in the engine as well as the members from the - /// script attached to the , regardless of the scripting language it was written in. + /// script attached to the , regardless of the scripting language it was written in. /// /// /// - /// This sample shows how to use to dynamically access the engine members of a . + /// This sample shows how to use to dynamically access the engine members of a . /// /// dynamic sprite = GetNode("Sprite").DynamicGodotObject; /// sprite.add_child(this); @@ -30,7 +30,7 @@ namespace Godot /// /// /// - /// This sample shows how to use to dynamically access the members of the script attached to a . + /// This sample shows how to use to dynamically access the members of the script attached to a . /// /// dynamic childNode = GetNode("ChildNode").DynamicGodotObject; /// @@ -54,18 +54,18 @@ namespace Godot public class DynamicGodotObject : DynamicObject { /// - /// Gets the associated with this . + /// Gets the associated with this . /// public Object Value { get; } /// - /// Initializes a new instance of the class. + /// Initializes a new instance of the class. /// /// - /// The that will be associated with this . + /// The that will be associated with this . /// - /// - /// Thrown when the parameter is null. + /// + /// Thrown when the parameter is . /// public DynamicGodotObject(Object godotObject) { @@ -75,11 +75,13 @@ namespace Godot this.Value = godotObject; } + /// public override IEnumerable GetDynamicMemberNames() { return godot_icall_DynamicGodotObject_SetMemberList(Object.GetPtr(Value)); } + /// public override bool TryBinaryOperation(BinaryOperationBinder binder, object arg, out object result) { switch (binder.Operation) @@ -121,6 +123,7 @@ namespace Godot return base.TryBinaryOperation(binder, arg, out result); } + /// public override bool TryConvert(ConvertBinder binder, out object result) { if (binder.Type == typeof(Object)) @@ -139,6 +142,7 @@ namespace Godot return base.TryConvert(binder, out result); } + /// public override bool TryGetIndex(GetIndexBinder binder, object[] indexes, out object result) { if (indexes.Length == 1) @@ -152,16 +156,19 @@ namespace Godot return base.TryGetIndex(binder, indexes, out result); } + /// public override bool TryGetMember(GetMemberBinder binder, out object result) { return godot_icall_DynamicGodotObject_GetMember(Object.GetPtr(Value), binder.Name, out result); } + /// public override bool TryInvokeMember(InvokeMemberBinder binder, object[] args, out object result) { return godot_icall_DynamicGodotObject_InvokeMember(Object.GetPtr(Value), binder.Name, args, out result); } + /// public override bool TrySetIndex(SetIndexBinder binder, object[] indexes, object value) { if (indexes.Length == 1) @@ -175,6 +182,7 @@ namespace Godot return base.TrySetIndex(binder, indexes, value); } + /// public override bool TrySetMember(SetMemberBinder binder, object value) { return godot_icall_DynamicGodotObject_SetMember(Object.GetPtr(Value), binder.Name, value); diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Extensions/NodeExtensions.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Extensions/NodeExtensions.cs index 5d16260f5d6..1dc21b6303b 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Extensions/NodeExtensions.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Extensions/NodeExtensions.cs @@ -1,42 +1,192 @@ +using System; + namespace Godot { public partial class Node { + /// + /// Fetches a node. The can be either a relative path (from + /// the current node) or an absolute path (in the scene tree) to a node. If the path + /// does not exist, a instance is returned and an error + /// is logged. Attempts to access methods on the return value will result in an + /// "Attempt to call <method> on a null instance." error. + /// Note: Fetching absolute paths only works when the node is inside the scene tree + /// (see ). + /// + /// + /// Example: Assume your current node is Character and the following tree: + /// + /// /root + /// /root/Character + /// /root/Character/Sword + /// /root/Character/Backpack/Dagger + /// /root/MyGame + /// /root/Swamp/Alligator + /// /root/Swamp/Mosquito + /// /root/Swamp/Goblin + /// + /// Possible paths are: + /// + /// GetNode("Sword"); + /// GetNode("Backpack/Dagger"); + /// GetNode("../Swamp/Alligator"); + /// GetNode("/root/MyGame"); + /// + /// + /// + /// The path to the node to fetch. + /// + /// Thrown when the given the fetched node can't be casted to the given type . + /// + /// The type to cast to. Should be a descendant of . + /// + /// The at the given . + /// public T GetNode(NodePath path) where T : class { return (T)(object)GetNode(path); } + /// + /// Fetches a node. The can be either a relative path (from + /// the current node) or an absolute path (in the scene tree) to a node. If the path + /// does not exist, a instance is returned and an error + /// is logged. Attempts to access methods on the return value will result in an + /// "Attempt to call <method> on a null instance." error. + /// Note: Fetching absolute paths only works when the node is inside the scene tree + /// (see ). + /// + /// + /// Example: Assume your current node is Character and the following tree: + /// + /// /root + /// /root/Character + /// /root/Character/Sword + /// /root/Character/Backpack/Dagger + /// /root/MyGame + /// /root/Swamp/Alligator + /// /root/Swamp/Mosquito + /// /root/Swamp/Goblin + /// + /// Possible paths are: + /// + /// GetNode("Sword"); + /// GetNode("Backpack/Dagger"); + /// GetNode("../Swamp/Alligator"); + /// GetNode("/root/MyGame"); + /// + /// + /// + /// The path to the node to fetch. + /// The type to cast to. Should be a descendant of . + /// + /// The at the given , or if not found. + /// public T GetNodeOrNull(NodePath path) where T : class { return GetNodeOrNull(path) as T; } + /// + /// Returns a child node by its index (see ). + /// This method is often used for iterating all children of a node. + /// Negative indices access the children from the last one. + /// To access a child node via its name, use . + /// + /// + /// Child index. + /// + /// Thrown when the given the fetched node can't be casted to the given type . + /// + /// The type to cast to. Should be a descendant of . + /// + /// The child at the given index . + /// public T GetChild(int idx) where T : class { return (T)(object)GetChild(idx); } + /// + /// Returns a child node by its index (see ). + /// This method is often used for iterating all children of a node. + /// Negative indices access the children from the last one. + /// To access a child node via its name, use . + /// + /// + /// Child index. + /// The type to cast to. Should be a descendant of . + /// + /// The child at the given index , or if not found. + /// public T GetChildOrNull(int idx) where T : class { return GetChild(idx) as T; } + /// + /// The node owner. A node can have any other node as owner (as long as it is + /// a valid parent, grandparent, etc. ascending in the tree). When saving a + /// node (using ), all the nodes it owns will be saved + /// with it. This allows for the creation of complex s, + /// with instancing and subinstancing. + /// + /// + /// + /// Thrown when the given the fetched node can't be casted to the given type . + /// + /// The type to cast to. Should be a descendant of . + /// + /// The owner . + /// public T GetOwner() where T : class { return (T)(object)Owner; } + /// + /// The node owner. A node can have any other node as owner (as long as it is + /// a valid parent, grandparent, etc. ascending in the tree). When saving a + /// node (using ), all the nodes it owns will be saved + /// with it. This allows for the creation of complex s, + /// with instancing and subinstancing. + /// + /// + /// The type to cast to. Should be a descendant of . + /// + /// The owner , or if there is no owner. + /// public T GetOwnerOrNull() where T : class { return Owner as T; } + /// + /// Returns the parent node of the current node, or a instance + /// if the node lacks a parent. + /// + /// + /// + /// Thrown when the given the fetched node can't be casted to the given type . + /// + /// The type to cast to. Should be a descendant of . + /// + /// The parent . + /// public T GetParent() where T : class { return (T)(object)GetParent(); } + /// + /// Returns the parent node of the current node, or a instance + /// if the node lacks a parent. + /// + /// + /// The type to cast to. Should be a descendant of . + /// + /// The parent , or if the node has no parent. + /// public T GetParentOrNull() where T : class { return GetParent() as T; diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Extensions/ObjectExtensions.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Extensions/ObjectExtensions.cs index 9ef09597500..e1f8773ccda 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Extensions/ObjectExtensions.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Extensions/ObjectExtensions.cs @@ -5,14 +5,34 @@ namespace Godot { public partial class Object { + /// + /// Returns whether is a valid object + /// (e.g. has not been deleted from memory). + /// + /// The instance to check. + /// If the instance is a valid object. public static bool IsInstanceValid(Object instance) { return instance != null && instance.NativeInstance != IntPtr.Zero; } + /// + /// Returns a weak reference to an object, or + /// if the argument is invalid. + /// A weak reference to an object is not enough to keep the object alive: + /// when the only remaining references to a referent are weak references, + /// garbage collection is free to destroy the referent and reuse its memory + /// for something else. However, until the object is actually destroyed the + /// weak reference may return the object even if there are no strong references + /// to it. + /// + /// The object. + /// + /// The reference to the object or . + /// public static WeakRef WeakRef(Object obj) { - return godot_icall_Object_weakref(Object.GetPtr(obj)); + return godot_icall_Object_weakref(GetPtr(obj)); } [MethodImpl(MethodImplOptions.InternalCall)] diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Extensions/PackedSceneExtensions.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Extensions/PackedSceneExtensions.cs index 763f470504b..6f8b2598380 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Extensions/PackedSceneExtensions.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Extensions/PackedSceneExtensions.cs @@ -1,3 +1,5 @@ +using System; + namespace Godot { public partial class PackedScene @@ -5,20 +7,27 @@ namespace Godot /// /// Instantiates the scene's node hierarchy, erroring on failure. /// Triggers child scene instantiation(s). Triggers a - /// `Node.NotificationInstanced` notification on the root node. + /// notification on the root node. /// - /// The type to cast to. Should be a descendant of Node. + /// + /// + /// Thrown when the given the instantiated node can't be casted to the given type . + /// + /// The type to cast to. Should be a descendant of . + /// The instantiated scene. public T Instance(PackedScene.GenEditState editState = (PackedScene.GenEditState)0) where T : class { return (T)(object)Instance(editState); } /// - /// Instantiates the scene's node hierarchy, returning null on failure. + /// Instantiates the scene's node hierarchy, returning on failure. /// Triggers child scene instantiation(s). Triggers a - /// `Node.NotificationInstanced` notification on the root node. + /// notification on the root node. /// - /// The type to cast to. Should be a descendant of Node. + /// + /// The type to cast to. Should be a descendant of . + /// The instantiated scene. public T InstanceOrNull(PackedScene.GenEditState editState = (PackedScene.GenEditState)0) where T : class { return Instance(editState) as T; diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Extensions/ResourceLoaderExtensions.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Extensions/ResourceLoaderExtensions.cs index 5f64c09a898..49f3b52afee 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Extensions/ResourceLoaderExtensions.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Extensions/ResourceLoaderExtensions.cs @@ -1,7 +1,27 @@ +using System; + namespace Godot { public static partial class ResourceLoader { + /// + /// Loads a resource at the given , caching the result + /// for further access. + /// The registered instances are queried sequentially + /// to find the first one which can handle the file's extension, and then attempt + /// loading. If loading fails, the remaining ResourceFormatLoaders are also attempted. + /// An optional can be used to further specify the + /// type that should be handled by the . + /// Anything that inherits from can be used as a type hint, + /// for example . + /// If is , the resource cache will be bypassed and + /// the resource will be loaded anew. Otherwise, the cached resource will be returned if it exists. + /// Returns an empty resource if no could handle the file. + /// + /// + /// Thrown when the given the loaded resource can't be casted to the given type . + /// + /// The type to cast to. Should be a descendant of . public static T Load(string path, string typeHint = null, bool noCache = false) where T : class { return (T)(object)Load(path, typeHint, noCache); diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/GD.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/GD.cs index 87ff3416f72..45ff889656a 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/GD.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/GD.cs @@ -7,27 +7,77 @@ using System; using System.Collections.Generic; using System.Runtime.CompilerServices; -// TODO: Add comments describing what this class does. It is not obvious. - namespace Godot { + /// + /// Godot's global functions. + /// public static partial class GD { - public static object Bytes2Var(byte[] bytes, bool allow_objects = false) + /// + /// Decodes a byte array back to a Variant value. + /// If is decoding objects is allowed. + /// + /// WARNING: Deserialized object can contain code which gets executed. + /// Do not set to + /// if the serialized object comes from untrusted sources to avoid + /// potential security threats (remote code execution). + /// + /// Byte array that will be decoded to a Variant. + /// If objects should be decoded. + /// The decoded Variant. + public static object Bytes2Var(byte[] bytes, bool allowObjects = false) { - return godot_icall_GD_bytes2var(bytes, allow_objects); + return godot_icall_GD_bytes2var(bytes, allowObjects); } + /// + /// Converts from a Variant type to another in the best way possible. + /// The parameter uses the values. + /// + /// + /// + /// var a = new Vector2(1, 0); + /// // Prints 1 + /// GD.Print(a.Length()); + /// var b = GD.Convert(a, Variant.Type.String) + /// // Prints 6 as "(1, 0)" is 6 characters + /// GD.Print(b.Length); + /// + /// + /// The Variant converted to the given . public static object Convert(object what, Variant.Type type) { return godot_icall_GD_convert(what, type); } + /// + /// Converts from decibels to linear energy (audio). + /// + /// + /// Decibels to convert. + /// Audio volume as linear energy. public static real_t Db2Linear(real_t db) { return (real_t)Math.Exp(db * 0.11512925464970228420089957273422); } + /// + /// Returns the result of decreased by + /// * . + /// + /// + /// + /// // a = 59; + /// // float a = GD.DecTime(60, 10, 0.1f); + /// + /// + /// Value that will be decreased. + /// + /// Amount that will be decreased from for every . + /// + /// Times the will be decreased by + /// The decreased value. public static real_t DecTime(real_t value, real_t amount, real_t step) { real_t sgn = Mathf.Sign(value); @@ -38,6 +88,14 @@ namespace Godot return val * sgn; } + /// + /// Get the that refers to the function + /// with the given name in the + /// given object . + /// + /// The object that contains the function. + /// The name of the function. + /// A reference to the given object's function. public static FuncRef FuncRef(Object instance, string funcname) { var ret = new FuncRef(); @@ -56,106 +114,342 @@ namespace Godot return Array.ConvertAll(parameters, x => x?.ToString() ?? "null"); } + /// + /// Returns the integer hash of the variable passed. + /// + /// + /// + /// GD.Print(GD.Hash("a")); // Prints 177670 + /// + /// + /// Variable that will be hashed. + /// Hash of the variable passed. public static int Hash(object var) { return godot_icall_GD_hash(var); } + /// + /// Returns the that corresponds to . + /// All Objects have a unique instance ID. + /// + /// + /// + /// public class MyNode : Node + /// { + /// public string foo = "bar"; + /// + /// public override void _Ready() + /// { + /// ulong id = GetInstanceId(); + /// var inst = (MyNode)GD.InstanceFromId(Id); + /// GD.Print(inst.foo); // Prints bar + /// } + /// } + /// + /// + /// Instance ID of the Object to retrieve. + /// The instance. public static Object InstanceFromId(ulong instanceId) { return godot_icall_GD_instance_from_id(instanceId); } + /// + /// Converts from linear energy to decibels (audio). + /// This can be used to implement volume sliders that behave as expected (since volume isn't linear). + /// + /// + /// + /// + /// // "slider" refers to a node that inherits Range such as HSlider or VSlider. + /// // Its range must be configured to go from 0 to 1. + /// // Change the bus name if you'd like to change the volume of a specific bus only. + /// AudioServer.SetBusVolumeDb(AudioServer.GetBusIndex("Master"), GD.Linear2Db(slider.value)); + /// + /// + /// The linear energy to convert. + /// Audio as decibels. public static real_t Linear2Db(real_t linear) { return (real_t)(Math.Log(linear) * 8.6858896380650365530225783783321); } + /// + /// Loads a resource from the filesystem located at . + /// The resource is loaded on the method call (unless it's referenced already + /// elsewhere, e.g. in another script or in the scene), which might cause slight delay, + /// especially when loading scenes. To avoid unnecessary delays when loading something + /// multiple times, either store the resource in a variable. + /// + /// Note: Resource paths can be obtained by right-clicking on a resource in the FileSystem + /// dock and choosing "Copy Path" or by dragging the file from the FileSystem dock into the script. + /// + /// Important: The path must be absolute, a local path will just return . + /// This method is a simplified version of , which can be used + /// for more advanced scenarios. + /// + /// + /// + /// // Load a scene called main located in the root of the project directory and cache it in a variable. + /// var main = GD.Load("res://main.tscn"); // main will contain a PackedScene resource. + /// + /// + /// Path of the to load. + /// The loaded . public static Resource Load(string path) { return ResourceLoader.Load(path); } + /// + /// Loads a resource from the filesystem located at . + /// The resource is loaded on the method call (unless it's referenced already + /// elsewhere, e.g. in another script or in the scene), which might cause slight delay, + /// especially when loading scenes. To avoid unnecessary delays when loading something + /// multiple times, either store the resource in a variable. + /// + /// Note: Resource paths can be obtained by right-clicking on a resource in the FileSystem + /// dock and choosing "Copy Path" or by dragging the file from the FileSystem dock into the script. + /// + /// Important: The path must be absolute, a local path will just return . + /// This method is a simplified version of , which can be used + /// for more advanced scenarios. + /// + /// + /// + /// // Load a scene called main located in the root of the project directory and cache it in a variable. + /// var main = GD.Load<PackedScene>("res://main.tscn"); // main will contain a PackedScene resource. + /// + /// + /// Path of the to load. + /// The type to cast to. Should be a descendant of . public static T Load(string path) where T : class { return ResourceLoader.Load(path); } + /// + /// Pushes an error message to Godot's built-in debugger and to the OS terminal. + /// + /// Note: Errors printed this way will not pause project execution. + /// To print an error message and pause project execution in debug builds, + /// use [code]assert(false, "test error")[/code] instead. + /// + /// + /// + /// GD.PushError("test_error"); // Prints "test error" to debugger and terminal as error call + /// + /// + /// Error message. public static void PushError(string message) { godot_icall_GD_pusherror(message); } + /// + /// Pushes a warning message to Godot's built-in debugger and to the OS terminal. + /// + /// + /// GD.PushWarning("test warning"); // Prints "test warning" to debugger and terminal as warning call + /// + /// Warning message. public static void PushWarning(string message) { godot_icall_GD_pushwarning(message); } + /// + /// Converts one or more arguments of any type to string in the best way possible + /// and prints them to the console. + /// + /// Note: Consider using and + /// to print error and warning messages instead of . + /// This distinguishes them from print messages used for debugging purposes, + /// while also displaying a stack trace when an error or warning is printed. + /// + /// + /// + /// var a = new int[] { 1, 2, 3 }; + /// GD.Print("a", "b", a); // Prints ab[1, 2, 3] + /// + /// + /// Arguments that will be printed. public static void Print(params object[] what) { godot_icall_GD_print(GetPrintParams(what)); } + /// + /// Prints the current stack trace information to the console. + /// public static void PrintStack() { Print(System.Environment.StackTrace); } + /// + /// Prints one or more arguments to strings in the best way possible to standard error line. + /// + /// + /// + /// GD.PrintErr("prints to stderr"); + /// + /// + /// Arguments that will be printed. public static void PrintErr(params object[] what) { godot_icall_GD_printerr(GetPrintParams(what)); } + /// + /// Prints one or more arguments to strings in the best way possible to console. + /// No newline is added at the end. + /// + /// Note: Due to limitations with Godot's built-in console, this only prints to the terminal. + /// If you need to print in the editor, use another method, such as . + /// + /// + /// + /// GD.PrintRaw("A"); + /// GD.PrintRaw("B"); + /// // Prints AB + /// + /// + /// Arguments that will be printed. public static void PrintRaw(params object[] what) { godot_icall_GD_printraw(GetPrintParams(what)); } + /// + /// Prints one or more arguments to the console with a space between each argument. + /// + /// + /// + /// GD.PrintS("A", "B", "C"); // Prints A B C + /// + /// + /// Arguments that will be printed. public static void PrintS(params object[] what) { godot_icall_GD_prints(GetPrintParams(what)); } + /// + /// Prints one or more arguments to the console with a tab between each argument. + /// + /// + /// + /// GD.PrintT("A", "B", "C"); // Prints A B C + /// + /// + /// Arguments that will be printed. public static void PrintT(params object[] what) { godot_icall_GD_printt(GetPrintParams(what)); } + /// + /// Returns a random floating point value between 0.0 and 1.0 (inclusive). + /// + /// + /// + /// GD.Randf(); // Returns e.g. 0.375671 + /// + /// + /// A random number. public static float Randf() { return godot_icall_GD_randf(); } + /// + /// Returns a random unsigned 32-bit integer. + /// Use remainder to obtain a random value in the interval [0, N - 1] (where N is smaller than 2^32). + /// + /// + /// + /// GD.Randi(); // Returns random integer between 0 and 2^32 - 1 + /// GD.Randi() % 20; // Returns random integer between 0 and 19 + /// GD.Randi() % 100; // Returns random integer between 0 and 99 + /// GD.Randi() % 100 + 1; // Returns random integer between 1 and 100 + /// + /// + /// A random number. public static uint Randi() { return godot_icall_GD_randi(); } + /// + /// Randomizes the seed (or the internal state) of the random number generator. + /// Current implementation reseeds using a number based on time. + /// + /// Note: This method is called automatically when the project is run. + /// If you need to fix the seed to have reproducible results, use + /// to initialize the random number generator. + /// public static void Randomize() { godot_icall_GD_randomize(); } + /// + /// Returns a random floating point value on the interval between + /// and (inclusive). + /// + /// + /// + /// GD.PrintS(GD.RandRange(-10.0, 10.0), GD.RandRange(-10.0, 10.0)); // Prints e.g. -3.844535 7.45315 + /// + /// + /// A random number inside the given range. public static double RandRange(double from, double to) { return godot_icall_GD_rand_range(from, to); } + /// + /// Returns a random unsigned 32-bit integer, using the given . + /// The will return the new seed. + /// + /// Seed to use to generate the random number. + /// Seed used by the random number generator. + /// A random number. public static uint RandSeed(ulong seed, out ulong newSeed) { return godot_icall_GD_rand_seed(seed, out newSeed); } + /// + /// Returns a that iterates from + /// 0 to in steps of 1. + /// + /// The last index. public static IEnumerable Range(int end) { return Range(0, end, 1); } + /// + /// Returns a that iterates from + /// to in steps of 1. + /// + /// The first index. + /// The last index. public static IEnumerable Range(int start, int end) { return Range(start, end, 1); } + /// + /// Returns a that iterates from + /// to in steps of . + /// + /// The first index. + /// The last index. + /// The amount by which to increment the index on each iteration. public static IEnumerable Range(int start, int end, int step) { if (end < start && step > 0) @@ -176,31 +470,82 @@ namespace Godot } } + /// + /// Sets seed for the random number generator. + /// + /// Seed that will be used. public static void Seed(ulong seed) { godot_icall_GD_seed(seed); } + /// + /// Converts one or more arguments of any type to string in the best way possible. + /// + /// Arguments that will converted to string. + /// The string formed by the given arguments. public static string Str(params object[] what) { return godot_icall_GD_str(what); } + /// + /// Converts a formatted string that was returned by to the original value. + /// + /// + /// + /// string a = "{\"a\": 1, \"b\": 2 }"; + /// var b = (Godot.Collections.Dictionary)GD.Str2Var(a); + /// GD.Print(b["a"]); // Prints 1 + /// + /// + /// String that will be converted to Variant. + /// The decoded Variant. public static object Str2Var(string str) { return godot_icall_GD_str2var(str); } + /// + /// Returns whether the given class exists in . + /// + /// If the class exists in . public static bool TypeExists(string type) { return godot_icall_GD_type_exists(type); } - public static byte[] Var2Bytes(object var, bool full_objects = false) + /// + /// Encodes a Variant value to a byte array. + /// If is encoding objects is allowed + /// (and can potentially include code). + /// Deserialization can be done with . + /// + /// Variant that will be encoded. + /// If objects should be serialized. + /// The Variant encoded as an array of bytes. + public static byte[] Var2Bytes(object var, bool fullObjects = false) { - return godot_icall_GD_var2bytes(var, full_objects); + return godot_icall_GD_var2bytes(var, fullObjects); } + /// + /// Converts a Variant to a formatted string that + /// can later be parsed using . + /// + /// + /// + /// var a = new Godot.Collections.Dictionary { ["a"] = 1, ["b"] = 2 }; + /// GD.Print(GD.Var2Str(a)); + /// // Prints + /// // { + /// // "a": 1, + /// // "b": 2 + /// // } + /// + /// + /// Variant that will be converted to string. + /// The Variant encoded as a string. public static string Var2Str(object var) { return godot_icall_GD_var2str(var); diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/MarshalUtils.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/MarshalUtils.cs index f508211f686..80bda4e2f5f 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/MarshalUtils.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/MarshalUtils.cs @@ -7,56 +7,131 @@ namespace Godot { /// /// Returns if the generic type definition of - /// is ; otherwise returns . + /// is ; otherwise returns . /// - /// - /// is not a generic type. That is, IsGenericType returns false. + /// + /// Thrown when the given is not a generic type. + /// That is, returns . /// - static bool TypeIsGenericArray(Type type) => - type.GetGenericTypeDefinition() == typeof(Godot.Collections.Array<>); + private static bool TypeIsGenericArray(Type type) => + type.GetGenericTypeDefinition() == typeof(Collections.Array<>); /// /// Returns if the generic type definition of - /// is ; otherwise returns . + /// is ; otherwise returns . /// - /// - /// is not a generic type. That is, IsGenericType returns false. + /// + /// Thrown when the given is not a generic type. + /// That is, returns . /// - static bool TypeIsGenericDictionary(Type type) => - type.GetGenericTypeDefinition() == typeof(Godot.Collections.Dictionary<,>); + private static bool TypeIsGenericDictionary(Type type) => + type.GetGenericTypeDefinition() == typeof(Collections.Dictionary<,>); - static bool TypeIsSystemGenericList(Type type) => - type.GetGenericTypeDefinition() == typeof(System.Collections.Generic.List<>); + /// + /// Returns if the generic type definition of + /// is ; otherwise returns . + /// + /// + /// Thrown when the given is not a generic type. + /// That is, returns . + /// + private static bool TypeIsSystemGenericList(Type type) => + type.GetGenericTypeDefinition() == typeof(List<>); - static bool TypeIsSystemGenericDictionary(Type type) => - type.GetGenericTypeDefinition() == typeof(System.Collections.Generic.Dictionary<,>); + /// + /// Returns if the generic type definition of + /// is ; otherwise returns . + /// + /// + /// Thrown when the given is not a generic type. + /// That is, returns . + /// + private static bool TypeIsSystemGenericDictionary(Type type) => + type.GetGenericTypeDefinition() == typeof(Dictionary<,>); - static bool TypeIsGenericIEnumerable(Type type) => type.GetGenericTypeDefinition() == typeof(IEnumerable<>); + /// + /// Returns if the generic type definition of + /// is ; otherwise returns . + /// + /// + /// Thrown when the given is not a generic type. + /// That is, returns . + /// + private static bool TypeIsGenericIEnumerable(Type type) => type.GetGenericTypeDefinition() == typeof(IEnumerable<>); - static bool TypeIsGenericICollection(Type type) => type.GetGenericTypeDefinition() == typeof(ICollection<>); + /// + /// Returns if the generic type definition of + /// is ; otherwise returns . + /// + /// + /// Thrown when the given is not a generic type. + /// That is, returns . + /// + private static bool TypeIsGenericICollection(Type type) => type.GetGenericTypeDefinition() == typeof(ICollection<>); - static bool TypeIsGenericIDictionary(Type type) => type.GetGenericTypeDefinition() == typeof(IDictionary<,>); + /// + /// Returns if the generic type definition of + /// is ; otherwise returns . + /// + /// + /// Thrown when the given is not a generic type. + /// That is, returns . + /// + private static bool TypeIsGenericIDictionary(Type type) => type.GetGenericTypeDefinition() == typeof(IDictionary<,>); - static void ArrayGetElementType(Type arrayType, out Type elementType) + /// + /// Gets the element type for the given . + /// + /// Type for the generic array. + /// Element type for the generic array. + /// + /// Thrown when the given is not a generic type. + /// That is, returns . + /// + private static void ArrayGetElementType(Type arrayType, out Type elementType) { elementType = arrayType.GetGenericArguments()[0]; } - static void DictionaryGetKeyValueTypes(Type dictionaryType, out Type keyType, out Type valueType) + /// + /// Gets the key type and the value type for the given . + /// + /// The type for the generic dictionary. + /// Key type for the generic dictionary. + /// Value type for the generic dictionary. + /// + /// Thrown when the given is not a generic type. + /// That is, returns . + /// + private static void DictionaryGetKeyValueTypes(Type dictionaryType, out Type keyType, out Type valueType) { var genericArgs = dictionaryType.GetGenericArguments(); keyType = genericArgs[0]; valueType = genericArgs[1]; } - static Type MakeGenericArrayType(Type elemType) + /// + /// Constructs a new from + /// where the generic type for the elements is . + /// + /// Element type for the array. + /// The generic array type with the specified element type. + private static Type MakeGenericArrayType(Type elemType) { - return typeof(Godot.Collections.Array<>).MakeGenericType(elemType); + return typeof(Collections.Array<>).MakeGenericType(elemType); } - static Type MakeGenericDictionaryType(Type keyType, Type valueType) + /// + /// Constructs a new from + /// where the generic type for the keys is and + /// for the values is . + /// + /// Key type for the dictionary. + /// Key type for the dictionary. + /// The generic dictionary type with the specified key and value types. + private static Type MakeGenericDictionaryType(Type keyType, Type valueType) { - return typeof(Godot.Collections.Dictionary<,>).MakeGenericType(keyType, valueType); + return typeof(Collections.Dictionary<,>).MakeGenericType(keyType, valueType); } } } diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Mathf.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Mathf.cs index 0ba3849da6a..149de412159 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Mathf.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Mathf.cs @@ -7,6 +7,9 @@ using System; namespace Godot { + /// + /// Provides constants and static methods for common mathematical functions. + /// public static partial class Mathf { // Define constants with Decimal precision and cast down to double or float. @@ -19,18 +22,18 @@ namespace Godot /// /// Constant that represents how many times the diameter of a circle - /// fits around its perimeter. This is equivalent to `Mathf.Tau / 2`. + /// fits around its perimeter. This is equivalent to Mathf.Tau / 2. /// // 3.1415927f and 3.14159265358979 public const real_t Pi = (real_t)3.1415926535897932384626433833M; /// - /// Positive infinity. For negative infinity, use `-Mathf.Inf`. + /// Positive infinity. For negative infinity, use -Mathf.Inf. /// public const real_t Inf = real_t.PositiveInfinity; /// - /// "Not a Number", an invalid value. `NaN` has special properties, including + /// "Not a Number", an invalid value. NaN has special properties, including /// that it is not equal to itself. It is output by some invalid operations, /// such as dividing zero by zero. /// @@ -42,68 +45,79 @@ namespace Godot private const real_t Rad2DegConst = (real_t)57.295779513082320876798154814M; /// - /// Returns the absolute value of `s` (i.e. positive value). + /// Returns the absolute value of (i.e. positive value). /// /// The input number. - /// The absolute value of `s`. + /// The absolute value of . public static int Abs(int s) { return Math.Abs(s); } /// - /// Returns the absolute value of `s` (i.e. positive value). + /// Returns the absolute value of (i.e. positive value). /// /// The input number. - /// The absolute value of `s`. + /// The absolute value of . public static real_t Abs(real_t s) { return Math.Abs(s); } /// - /// Returns the arc cosine of `s` in radians. Use to get the angle of cosine s. + /// Returns the arc cosine of in radians. + /// Use to get the angle of cosine . /// /// The input cosine value. Must be on the range of -1.0 to 1.0. - /// An angle that would result in the given cosine value. On the range `0` to `Tau/2`. + /// + /// An angle that would result in the given cosine value. On the range 0 to Tau/2. + /// public static real_t Acos(real_t s) { return (real_t)Math.Acos(s); } /// - /// Returns the arc sine of `s` in radians. Use to get the angle of sine s. + /// Returns the arc sine of in radians. + /// Use to get the angle of sine . /// /// The input sine value. Must be on the range of -1.0 to 1.0. - /// An angle that would result in the given sine value. On the range `-Tau/4` to `Tau/4`. + /// + /// An angle that would result in the given sine value. On the range -Tau/4 to Tau/4. + /// public static real_t Asin(real_t s) { return (real_t)Math.Asin(s); } /// - /// Returns the arc tangent of `s` in radians. Use to get the angle of tangent s. + /// Returns the arc tangent of in radians. + /// Use to get the angle of tangent . /// /// The method cannot know in which quadrant the angle should fall. - /// See if you have both `y` and `x`. + /// See if you have both y and x. /// /// The input tangent value. - /// An angle that would result in the given tangent value. On the range `-Tau/4` to `Tau/4`. + /// + /// An angle that would result in the given tangent value. On the range -Tau/4 to Tau/4. + /// public static real_t Atan(real_t s) { return (real_t)Math.Atan(s); } /// - /// Returns the arc tangent of `y` and `x` in radians. Use to get the angle - /// of the tangent of `y/x`. To compute the value, the method takes into + /// Returns the arc tangent of and in radians. + /// Use to get the angle of the tangent of y/x. To compute the value, the method takes into /// account the sign of both arguments in order to determine the quadrant. /// /// Important note: The Y coordinate comes first, by convention. /// /// The Y coordinate of the point to find the angle to. /// The X coordinate of the point to find the angle to. - /// An angle that would result in the given tangent value. On the range `-Tau/2` to `Tau/2`. + /// + /// An angle that would result in the given tangent value. On the range -Tau/2 to Tau/2. + /// public static real_t Atan2(real_t y, real_t x) { return (real_t)Math.Atan2(y, x); @@ -123,17 +137,18 @@ namespace Godot } /// - /// Rounds `s` upward (towards positive infinity). + /// Rounds upward (towards positive infinity). /// /// The number to ceil. - /// The smallest whole number that is not less than `s`. + /// The smallest whole number that is not less than . public static real_t Ceil(real_t s) { return (real_t)Math.Ceiling(s); } /// - /// Clamps a `value` so that it is not less than `min` and not more than `max`. + /// Clamps a so that it is not less than + /// and not more than . /// /// The value to clamp. /// The minimum allowed value. @@ -145,7 +160,8 @@ namespace Godot } /// - /// Clamps a `value` so that it is not less than `min` and not more than `max`. + /// Clamps a so that it is not less than + /// and not more than . /// /// The value to clamp. /// The minimum allowed value. @@ -157,7 +173,7 @@ namespace Godot } /// - /// Returns the cosine of angle `s` in radians. + /// Returns the cosine of angle in radians. /// /// The angle in radians. /// The cosine of that angle. @@ -167,7 +183,7 @@ namespace Godot } /// - /// Returns the hyperbolic cosine of angle `s` in radians. + /// Returns the hyperbolic cosine of angle in radians. /// /// The angle in radians. /// The hyperbolic cosine of that angle. @@ -187,12 +203,14 @@ namespace Godot } /// - /// Easing function, based on exponent. The curve values are: - /// `0` is constant, `1` is linear, `0` to `1` is ease-in, `1` or more is ease-out. + /// Easing function, based on exponent. The values are: + /// 0 is constant, 1 is linear, 0 to 1 is ease-in, 1 or more is ease-out. /// Negative values are in-out/out-in. /// /// The value to ease. - /// `0` is constant, `1` is linear, `0` to `1` is ease-in, `1` or more is ease-out. + /// + /// 0 is constant, 1 is linear, 0 to 1 is ease-in, 1 or more is ease-out. + /// /// The eased value. public static real_t Ease(real_t s, real_t curve) { @@ -230,20 +248,20 @@ namespace Godot /// /// The natural exponential function. It raises the mathematical - /// constant `e` to the power of `s` and returns it. + /// constant e to the power of and returns it. /// - /// The exponent to raise `e` to. - /// `e` raised to the power of `s`. + /// The exponent to raise e to. + /// e raised to the power of . public static real_t Exp(real_t s) { return (real_t)Math.Exp(s); } /// - /// Rounds `s` downward (towards negative infinity). + /// Rounds downward (towards negative infinity). /// /// The number to floor. - /// The largest whole number that is not more than `s`. + /// The largest whole number that is not more than . public static real_t Floor(real_t s) { return (real_t)Math.Floor(s); @@ -263,12 +281,13 @@ namespace Godot } /// - /// Returns true if `a` and `b` are approximately equal to each other. + /// Returns if and are approximately equal + /// to each other. /// The comparison is done using a tolerance calculation with . /// /// One of the values. /// The other value. - /// A bool for whether or not the two values are approximately equal. + /// A for whether or not the two values are approximately equal. public static bool IsEqualApprox(real_t a, real_t b) { // Check for exact equality first, required to handle "infinity" values. @@ -286,33 +305,33 @@ namespace Godot } /// - /// Returns whether `s` is an infinity value (either positive infinity or negative infinity). + /// Returns whether is an infinity value (either positive infinity or negative infinity). /// /// The value to check. - /// A bool for whether or not the value is an infinity value. + /// A for whether or not the value is an infinity value. public static bool IsInf(real_t s) { return real_t.IsInfinity(s); } /// - /// Returns whether `s` is a `NaN` ("Not a Number" or invalid) value. + /// Returns whether is a NaN ("Not a Number" or invalid) value. /// /// The value to check. - /// A bool for whether or not the value is a `NaN` value. + /// A for whether or not the value is a NaN value. public static bool IsNaN(real_t s) { return real_t.IsNaN(s); } /// - /// Returns true if `s` is approximately zero. + /// Returns if is approximately zero. /// The comparison is done using a tolerance calculation with . /// /// This method is faster than using with one value as zero. /// /// The value to check. - /// A bool for whether or not the value is nearly zero. + /// A for whether or not the value is nearly zero. public static bool IsZeroApprox(real_t s) { return Abs(s) < Epsilon; @@ -354,7 +373,7 @@ namespace Godot /// Note: This is not the same as the "log" function on most calculators, which uses a base 10 logarithm. /// /// The input value. - /// The natural log of `s`. + /// The natural log of . public static real_t Log(real_t s) { return (real_t)Math.Log(s); @@ -405,9 +424,9 @@ namespace Godot } /// - /// Moves `from` toward `to` by the `delta` value. + /// Moves toward by the value. /// - /// Use a negative delta value to move away. + /// Use a negative value to move away. /// /// The start value. /// The value to move towards. @@ -419,7 +438,7 @@ namespace Godot } /// - /// Returns the nearest larger power of 2 for the integer `value`. + /// Returns the nearest larger power of 2 for the integer . /// /// The input value. /// The nearest larger power of 2. @@ -437,8 +456,9 @@ namespace Godot /// /// Converts a 2D point expressed in the polar coordinate - /// system (a distance from the origin `r` and an angle `th`) - /// to the cartesian coordinate system (X and Y axis). + /// system (a distance from the origin + /// and an angle ) to the cartesian + /// coordinate system (X and Y axis). /// /// The distance from the origin. /// The angle of the point. @@ -449,10 +469,10 @@ namespace Godot } /// - /// Performs a canonical Modulus operation, where the output is on the range `[0, b)`. + /// Performs a canonical Modulus operation, where the output is on the range [0, ). /// /// The dividend, the primary input. - /// The divisor. The output is on the range `[0, b)`. + /// The divisor. The output is on the range [0, ). /// The resulting output. public static int PosMod(int a, int b) { @@ -465,10 +485,10 @@ namespace Godot } /// - /// Performs a canonical Modulus operation, where the output is on the range `[0, b)`. + /// Performs a canonical Modulus operation, where the output is on the range [0, ). /// /// The dividend, the primary input. - /// The divisor. The output is on the range `[0, b)`. + /// The divisor. The output is on the range [0, ). /// The resulting output. public static real_t PosMod(real_t a, real_t b) { @@ -481,11 +501,11 @@ namespace Godot } /// - /// Returns the result of `x` raised to the power of `y`. + /// Returns the result of raised to the power of . /// /// The base. /// The exponent. - /// `x` raised to the power of `y`. + /// raised to the power of . public static real_t Pow(real_t x, real_t y) { return (real_t)Math.Pow(x, y); @@ -502,7 +522,7 @@ namespace Godot } /// - /// Rounds `s` to the nearest whole number, + /// Rounds to the nearest whole number, /// with halfway cases rounded towards the nearest multiple of two. /// /// The number to round. @@ -513,10 +533,11 @@ namespace Godot } /// - /// Returns the sign of `s`: `-1` or `1`. Returns `0` if `s` is `0`. + /// Returns the sign of : -1 or 1. + /// Returns 0 if is 0. /// /// The input number. - /// One of three possible values: `1`, `-1`, or `0`. + /// One of three possible values: 1, -1, or 0. public static int Sign(int s) { if (s == 0) @@ -525,10 +546,11 @@ namespace Godot } /// - /// Returns the sign of `s`: `-1` or `1`. Returns `0` if `s` is `0`. + /// Returns the sign of : -1 or 1. + /// Returns 0 if is 0. /// /// The input number. - /// One of three possible values: `1`, `-1`, or `0`. + /// One of three possible values: 1, -1, or 0. public static int Sign(real_t s) { if (s == 0) @@ -537,7 +559,7 @@ namespace Godot } /// - /// Returns the sine of angle `s` in radians. + /// Returns the sine of angle in radians. /// /// The angle in radians. /// The sine of that angle. @@ -547,7 +569,7 @@ namespace Godot } /// - /// Returns the hyperbolic sine of angle `s` in radians. + /// Returns the hyperbolic sine of angle in radians. /// /// The angle in radians. /// The hyperbolic sine of that angle. @@ -557,8 +579,8 @@ namespace Godot } /// - /// Returns a number smoothly interpolated between `from` and `to`, - /// based on the `weight`. Similar to , + /// Returns a number smoothly interpolated between and , + /// based on the . Similar to , /// but interpolates faster at the beginning and slower at the end. /// /// The start value for interpolation. @@ -576,12 +598,12 @@ namespace Godot } /// - /// Returns the square root of `s`, where `s` is a non-negative number. + /// Returns the square root of , where is a non-negative number. /// - /// If you need negative inputs, use `System.Numerics.Complex`. + /// If you need negative inputs, use . /// /// The input number. Must not be negative. - /// The square root of `s`. + /// The square root of . public static real_t Sqrt(real_t s) { return (real_t)Math.Sqrt(s); @@ -620,9 +642,8 @@ namespace Godot } /// - /// Snaps float value `s` to a given `step`. - /// This can also be used to round a floating point - /// number to an arbitrary number of decimals. + /// Snaps float value to a given . + /// This can also be used to round a floating point number to an arbitrary number of decimals. /// /// The value to stepify. /// The step size to snap to. @@ -638,7 +659,7 @@ namespace Godot } /// - /// Returns the tangent of angle `s` in radians. + /// Returns the tangent of angle in radians. /// /// The angle in radians. /// The tangent of that angle. @@ -648,7 +669,7 @@ namespace Godot } /// - /// Returns the hyperbolic tangent of angle `s` in radians. + /// Returns the hyperbolic tangent of angle in radians. /// /// The angle in radians. /// The hyperbolic tangent of that angle. @@ -658,8 +679,9 @@ namespace Godot } /// - /// Wraps `value` between `min` and `max`. Usable for creating loop-alike - /// behavior or infinite surfaces. If `min` is `0`, this is equivalent + /// Wraps between and . + /// Usable for creating loop-alike behavior or infinite surfaces. + /// If is 0, this is equivalent /// to , so prefer using that instead. /// /// The value to wrap. @@ -673,8 +695,9 @@ namespace Godot } /// - /// Wraps `value` between `min` and `max`. Usable for creating loop-alike - /// behavior or infinite surfaces. If `min` is `0`, this is equivalent + /// Wraps between and . + /// Usable for creating loop-alike behavior or infinite surfaces. + /// If is 0, this is equivalent /// to , so prefer using that instead. /// /// The value to wrap. diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/MathfEx.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/MathfEx.cs index 0888e33090d..9bb73ce7dd1 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/MathfEx.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/MathfEx.cs @@ -12,7 +12,7 @@ namespace Godot // Define constants with Decimal precision and cast down to double or float. /// - /// The natural number `e`. + /// The natural number e. /// public const real_t E = (real_t)2.7182818284590452353602874714M; // 2.7182817f and 2.718281828459045 @@ -23,7 +23,7 @@ namespace Godot /// /// A very small number used for float comparison with error tolerance. - /// 1e-06 with single-precision floats, but 1e-14 if `REAL_T_IS_DOUBLE`. + /// 1e-06 with single-precision floats, but 1e-14 if REAL_T_IS_DOUBLE. /// #if REAL_T_IS_DOUBLE public const real_t Epsilon = 1e-14; // Epsilon size should depend on the precision used. @@ -44,7 +44,7 @@ namespace Godot /// /// Returns the amount of digits after the decimal place. /// - /// The input value. + /// The input value. /// The amount of digits. public static int DecimalCount(decimal s) { @@ -52,48 +52,51 @@ namespace Godot } /// - /// Rounds `s` upward (towards positive infinity). + /// Rounds upward (towards positive infinity). /// - /// This is the same as , but returns an `int`. + /// This is the same as , but returns an int. /// /// The number to ceil. - /// The smallest whole number that is not less than `s`. + /// The smallest whole number that is not less than . public static int CeilToInt(real_t s) { return (int)Math.Ceiling(s); } /// - /// Rounds `s` downward (towards negative infinity). + /// Rounds downward (towards negative infinity). /// - /// This is the same as , but returns an `int`. + /// This is the same as , but returns an int. /// /// The number to floor. - /// The largest whole number that is not more than `s`. + /// The largest whole number that is not more than . public static int FloorToInt(real_t s) { return (int)Math.Floor(s); } /// + /// Rounds to the nearest whole number. /// + /// This is the same as , but returns an int. /// - /// - /// + /// The number to round. + /// The rounded number. public static int RoundToInt(real_t s) { return (int)Math.Round(s); } /// - /// Returns true if `a` and `b` are approximately equal to each other. + /// Returns if and are approximately + /// equal to each other. /// The comparison is done using the provided tolerance value. /// If you want the tolerance to be calculated for you, use . /// /// One of the values. /// The other value. /// The pre-calculated tolerance value. - /// A bool for whether or not the two values are equal. + /// A for whether or not the two values are equal. public static bool IsEqualApprox(real_t a, real_t b, real_t tolerance) { // Check for exact equality first, required to handle "infinity" values. diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/NodePath.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/NodePath.cs index 8c5872ba5ac..1377981ff4d 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/NodePath.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/NodePath.cs @@ -3,6 +3,42 @@ using System.Runtime.CompilerServices; namespace Godot { + /// + /// A pre-parsed relative or absolute path in a scene tree, + /// for use with and similar functions. + /// It can reference a node, a resource within a node, or a property + /// of a node or resource. + /// For instance, "Path2D/PathFollow2D/Sprite2D:texture:size" + /// would refer to the size property of the texture + /// resource on the node named "Sprite2D" which is a child of + /// the other named nodes in the path. + /// You will usually just pass a string to + /// and it will be automatically converted, but you may occasionally + /// want to parse a path ahead of time with NodePath. + /// Exporting a NodePath variable will give you a node selection widget + /// in the properties panel of the editor, which can often be useful. + /// A NodePath is composed of a list of slash-separated node names + /// (like a filesystem path) and an optional colon-separated list of + /// "subnames" which can be resources or properties. + /// + /// Note: In the editor, NodePath properties are automatically updated when moving, + /// renaming or deleting a node in the scene tree, but they are never updated at runtime. + /// + /// + /// Some examples of NodePaths include the following: + /// + /// // No leading slash means it is relative to the current node. + /// new NodePath("A"); // Immediate child A. + /// new NodePath("A/B"); // A's child B. + /// new NodePath("."); // The current node. + /// new NodePath(".."); // The parent node. + /// new NodePath("../C"); // A sibling node C. + /// // A leading slash means it is absolute from the SceneTree. + /// new NodePath("/root"); // Equivalent to GetTree().Root + /// new NodePath("/root/Main"); // If your main scene's root node were named "Main". + /// new NodePath("/root/MyAutoload"); // If you have an autoloaded node or scene. + /// + /// public sealed partial class NodePath : IDisposable { private bool disposed = false; @@ -25,6 +61,9 @@ namespace Godot Dispose(false); } + /// + /// Disposes of this . + /// public void Dispose() { Dispose(true); @@ -50,68 +89,183 @@ namespace Godot this.ptr = ptr; } + /// + /// The pointer to the native instance of this . + /// public IntPtr NativeInstance { get { return ptr; } } - public NodePath() : this(string.Empty) {} + /// + /// Constructs an empty . + /// + public NodePath() : this(string.Empty) { } + + /// + /// Constructs a from a string , + /// e.g.: "Path2D/PathFollow2D/Sprite2D:texture:size". + /// A path is absolute if it starts with a slash. Absolute paths + /// are only valid in the global scene tree, not within individual + /// scenes. In a relative path, "." and ".." indicate + /// the current node and its parent. + /// The "subnames" optionally included after the path to the target + /// node can point to resources or properties, and can also be nested. + /// + /// + /// Examples of valid NodePaths (assuming that those nodes exist and + /// have the referenced resources or properties): + /// + /// // Points to the Sprite2D node. + /// "Path2D/PathFollow2D/Sprite2D" + /// // Points to the Sprite2D node and its "texture" resource. + /// // GetNode() would retrieve "Sprite2D", while GetNodeAndResource() + /// // would retrieve both the Sprite2D node and the "texture" resource. + /// "Path2D/PathFollow2D/Sprite2D:texture" + /// // Points to the Sprite2D node and its "position" property. + /// "Path2D/PathFollow2D/Sprite2D:position" + /// // Points to the Sprite2D node and the "x" component of its "position" property. + /// "Path2D/PathFollow2D/Sprite2D:position:x" + /// // Absolute path (from "root") + /// "/root/Level/Path2D" + /// + /// + /// public NodePath(string path) { this.ptr = godot_icall_NodePath_Ctor(path); } + /// + /// Converts a string to a . + /// + /// The string to convert. public static implicit operator NodePath(string from) { return new NodePath(from); } + /// + /// Converts this to a string. + /// + /// The to convert. public static implicit operator string(NodePath from) { return godot_icall_NodePath_operator_String(NodePath.GetPtr(from)); } + /// + /// Converts this to a string. + /// + /// A string representation of this . public override string ToString() { return (string)this; } + /// + /// Returns a node path with a colon character (:) prepended, + /// transforming it to a pure property path with no node name (defaults + /// to resolving from the current node). + /// + /// + /// + /// // This will be parsed as a node path to the "x" property in the "position" node. + /// var nodePath = new NodePath("position:x"); + /// // This will be parsed as a node path to the "x" component of the "position" property in the current node. + /// NodePath propertyPath = nodePath.GetAsPropertyPath(); + /// GD.Print(propertyPath); // :position:x + /// + /// + /// The as a pure property path. public NodePath GetAsPropertyPath() { return new NodePath(godot_icall_NodePath_get_as_property_path(NodePath.GetPtr(this))); } + /// + /// Returns all subnames concatenated with a colon character (:) + /// as separator, i.e. the right side of the first colon in a node path. + /// + /// + /// + /// var nodepath = new NodePath("Path2D/PathFollow2D/Sprite2D:texture:load_path"); + /// GD.Print(nodepath.GetConcatenatedSubnames()); // texture:load_path + /// + /// + /// The subnames concatenated with :. public string GetConcatenatedSubnames() { return godot_icall_NodePath_get_concatenated_subnames(NodePath.GetPtr(this)); } + /// + /// Gets the node name indicated by (0 to ). + /// + /// + /// + /// var nodePath = new NodePath("Path2D/PathFollow2D/Sprite2D"); + /// GD.Print(nodePath.GetName(0)); // Path2D + /// GD.Print(nodePath.GetName(1)); // PathFollow2D + /// GD.Print(nodePath.GetName(2)); // Sprite + /// + /// + /// The name index. + /// The name at the given index . public string GetName(int idx) { return godot_icall_NodePath_get_name(NodePath.GetPtr(this), idx); } + /// + /// Gets the number of node names which make up the path. + /// Subnames (see ) are not included. + /// For example, "Path2D/PathFollow2D/Sprite2D" has 3 names. + /// + /// The number of node names which make up the path. public int GetNameCount() { return godot_icall_NodePath_get_name_count(NodePath.GetPtr(this)); } + /// + /// Gets the resource or property name indicated by (0 to ). + /// + /// The subname index. + /// The subname at the given index . public string GetSubname(int idx) { return godot_icall_NodePath_get_subname(NodePath.GetPtr(this), idx); } + /// + /// Gets the number of resource or property names ("subnames") in the path. + /// Each subname is listed after a colon character (:) in the node path. + /// For example, "Path2D/PathFollow2D/Sprite2D:texture:load_path" has 2 subnames. + /// + /// The number of subnames in the path. public int GetSubnameCount() { return godot_icall_NodePath_get_subname_count(NodePath.GetPtr(this)); } + /// + /// Returns if the node path is absolute (as opposed to relative), + /// which means that it starts with a slash character (/). Absolute node paths can + /// be used to access the root node ("/root") or autoloads (e.g. "/global" + /// if a "global" autoload was registered). + /// + /// If the is an absolute path. public bool IsAbsolute() { return godot_icall_NodePath_is_absolute(NodePath.GetPtr(this)); } + /// + /// Returns if the node path is empty. + /// + /// If the is empty. public bool IsEmpty() { return godot_icall_NodePath_is_empty(NodePath.GetPtr(this)); diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Object.base.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Object.base.cs index de80f7fddc1..21b7e5f9a55 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Object.base.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Object.base.cs @@ -12,6 +12,9 @@ namespace Godot internal IntPtr ptr; internal bool memoryOwn; + /// + /// Constructs a new . + /// public Object() : this(false) { if (ptr == IntPtr.Zero) @@ -23,6 +26,9 @@ namespace Godot this.memoryOwn = memoryOwn; } + /// + /// The pointer to the native instance of this . + /// public IntPtr NativeInstance { get { return ptr; } @@ -44,12 +50,18 @@ namespace Godot Dispose(false); } + /// + /// Disposes of this . + /// public void Dispose() { Dispose(true); GC.SuppressFinalize(this); } + /// + /// Disposes implementation of this . + /// protected virtual void Dispose(bool disposing) { if (disposed) @@ -73,13 +85,17 @@ namespace Godot disposed = true; } + /// + /// Converts this to a string. + /// + /// A string representation of this object. public override string ToString() { return godot_icall_Object_ToString(GetPtr(this)); } /// - /// Returns a new awaiter configured to complete when the instance + /// Returns a new awaiter configured to complete when the instance /// emits the signal specified by the parameter. /// /// @@ -101,13 +117,17 @@ namespace Godot /// } /// /// + /// + /// A that completes when + /// emits the . + /// public SignalAwaiter ToSignal(Object source, string signal) { return new SignalAwaiter(source, signal, this); } /// - /// Gets a new associated with this instance. + /// Gets a new associated with this instance. /// public dynamic DynamicObject => new DynamicGodotObject(this); diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Plane.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Plane.cs index 30f7512ae05..09aca2fd220 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Plane.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Plane.cs @@ -21,10 +21,10 @@ namespace Godot /// /// The normal of the plane, which must be normalized. - /// In the scalar equation of the plane `ax + by + cz = d`, this is - /// the vector `(a, b, c)`, where `d` is the property. + /// In the scalar equation of the plane ax + by + cz = d, this is + /// the vector (a, b, c), where d is the property. /// - /// Equivalent to `x`, `y`, and `z`. + /// Equivalent to , , and . public Vector3 Normal { get { return _normal; } @@ -82,8 +82,8 @@ namespace Godot /// /// The distance from the origin to the plane (in the direction of /// ). This value is typically non-negative. - /// In the scalar equation of the plane `ax + by + cz = d`, - /// this is `d`, while the `(a, b, c)` coordinates are represented + /// In the scalar equation of the plane ax + by + cz = d, + /// this is d, while the (a, b, c) coordinates are represented /// by the property. /// /// The plane's distance from the origin. @@ -92,7 +92,7 @@ namespace Godot /// /// The center of the plane, the point where the normal line intersects the plane. /// - /// Equivalent to multiplied by `D`. + /// Equivalent to multiplied by . public Vector3 Center { get @@ -107,7 +107,7 @@ namespace Godot } /// - /// Returns the shortest distance from this plane to the position `point`. + /// Returns the shortest distance from this plane to the position . /// /// The position to use for the calculation. /// The shortest distance. @@ -128,12 +128,12 @@ namespace Godot } /// - /// Returns true if point is inside the plane. + /// Returns if point is inside the plane. /// Comparison uses a custom minimum epsilon threshold. /// /// The point to check. /// The tolerance threshold. - /// A bool for whether or not the plane has the point. + /// A for whether or not the plane has the point. public bool HasPoint(Vector3 point, real_t epsilon = Mathf.Epsilon) { real_t dist = _normal.Dot(point) - D; @@ -141,12 +141,12 @@ namespace Godot } /// - /// Returns the intersection point of the three planes: `b`, `c`, - /// and this plane. If no intersection is found, `null` is returned. + /// Returns the intersection point of the three planes: , , + /// and this plane. If no intersection is found, is returned. /// /// One of the three planes to use in the calculation. /// One of the three planes to use in the calculation. - /// The intersection, or `null` if none is found. + /// The intersection, or if none is found. public Vector3? Intersect3(Plane b, Plane c) { real_t denom = _normal.Cross(b._normal).Dot(c._normal); @@ -164,13 +164,13 @@ namespace Godot } /// - /// Returns the intersection point of a ray consisting of the - /// position `from` and the direction normal `dir` with this plane. - /// If no intersection is found, `null` is returned. + /// Returns the intersection point of a ray consisting of the position + /// and the direction normal with this plane. + /// If no intersection is found, is returned. /// /// The start of the ray. /// The direction of the ray, normalized. - /// The intersection, or `null` if none is found. + /// The intersection, or if none is found. public Vector3? IntersectRay(Vector3 from, Vector3 dir) { real_t den = _normal.Dot(dir); @@ -193,12 +193,12 @@ namespace Godot /// /// Returns the intersection point of a line segment from - /// position `begin` to position `end` with this plane. - /// If no intersection is found, `null` is returned. + /// position to position with this plane. + /// If no intersection is found, is returned. /// /// The start of the line segment. /// The end of the line segment. - /// The intersection, or `null` if none is found. + /// The intersection, or if none is found. public Vector3? IntersectSegment(Vector3 begin, Vector3 end) { Vector3 segment = begin - end; @@ -221,10 +221,10 @@ namespace Godot } /// - /// Returns true if `point` is located above the plane. + /// Returns if is located above the plane. /// /// The point to check. - /// A bool for whether or not the point is above the plane. + /// A for whether or not the point is above the plane. public bool IsPointOver(Vector3 point) { return _normal.Dot(point) > D; @@ -247,7 +247,7 @@ namespace Godot } /// - /// Returns the orthogonal projection of `point` into the plane. + /// Returns the orthogonal projection of into the plane. /// /// The point to project. /// The projected point. @@ -262,27 +262,28 @@ namespace Godot private static readonly Plane _planeXY = new Plane(0, 0, 1, 0); /// - /// A plane that extends in the Y and Z axes (normal vector points +X). + /// A that extends in the Y and Z axes (normal vector points +X). /// - /// Equivalent to `new Plane(1, 0, 0, 0)`. + /// Equivalent to new Plane(1, 0, 0, 0). public static Plane PlaneYZ { get { return _planeYZ; } } /// - /// A plane that extends in the X and Z axes (normal vector points +Y). + /// A that extends in the X and Z axes (normal vector points +Y). /// - /// Equivalent to `new Plane(0, 1, 0, 0)`. + /// Equivalent to new Plane(0, 1, 0, 0). public static Plane PlaneXZ { get { return _planeXZ; } } /// - /// A plane that extends in the X and Y axes (normal vector points +Z). + /// A that extends in the X and Y axes (normal vector points +Z). /// - /// Equivalent to `new Plane(0, 0, 1, 0)`. + /// Equivalent to new Plane(0, 0, 1, 0). public static Plane PlaneXY { get { return _planeXY; } } /// - /// Constructs a plane from four values. `a`, `b` and `c` become the + /// Constructs a from four values. + /// , and become the /// components of the resulting plane's vector. - /// `d` becomes the plane's distance from the origin. + /// becomes the plane's distance from the origin. /// /// The X component of the plane's normal vector. /// The Y component of the plane's normal vector. @@ -295,7 +296,8 @@ namespace Godot } /// - /// Constructs a plane from a normal vector and the plane's distance to the origin. + /// Constructs a from a vector and + /// the plane's distance to the origin . /// /// The normal of the plane, must be normalized. /// The plane's distance from the origin. This value is typically non-negative. @@ -306,7 +308,7 @@ namespace Godot } /// - /// Constructs a plane from the three points, given in clockwise order. + /// Constructs a from the three points, given in clockwise order. /// /// The first point. /// The second point. @@ -333,6 +335,11 @@ namespace Godot return !left.Equals(right); } + /// + /// Returns if this plane and are equal. + /// + /// The other object to compare. + /// Whether or not the plane and the other object are equal. public override bool Equals(object obj) { if (obj is Plane) @@ -343,14 +350,19 @@ namespace Godot return false; } + /// + /// Returns if this plane and are equal. + /// + /// The other plane to compare. + /// Whether or not the planes are equal. public bool Equals(Plane other) { return _normal == other._normal && D == other.D; } /// - /// Returns true if this plane and `other` are approximately equal, by running - /// on each component. + /// Returns if this plane and are + /// approximately equal, by running on each component. /// /// The other plane to compare. /// Whether or not the planes are approximately equal. @@ -359,11 +371,19 @@ namespace Godot return _normal.IsEqualApprox(other._normal) && Mathf.IsEqualApprox(D, other.D); } + /// + /// Serves as the hash function for . + /// + /// A hash code for this plane. public override int GetHashCode() { return _normal.GetHashCode() ^ D.GetHashCode(); } + /// + /// Converts this to a string. + /// + /// A string representation of this plane. public override string ToString() { return String.Format("({0}, {1})", new object[] @@ -373,6 +393,10 @@ namespace Godot }); } + /// + /// Converts this to a string with the given . + /// + /// A string representation of this plane. public string ToString(string format) { return String.Format("({0}, {1})", new object[] diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Quat.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Quat.cs index bc8d715c96a..1d21c706dfb 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Quat.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Quat.cs @@ -12,10 +12,10 @@ namespace Godot /// A unit quaternion used for representing 3D rotations. /// Quaternions need to be normalized to be used for rotation. /// - /// It is similar to Basis, which implements matrix representation of - /// rotations, and can be parametrized using both an axis-angle pair - /// or Euler angles. Basis stores rotation, scale, and shearing, - /// while Quat only stores rotation. + /// It is similar to , which implements matrix + /// representation of rotations, and can be parametrized using both + /// an axis-angle pair or Euler angles. Basis stores rotation, scale, + /// and shearing, while Quat only stores rotation /// /// Due to its compactness and the way it is stored in memory, certain /// operations (obtaining axis-angle and performing SLERP, in particular) @@ -26,19 +26,19 @@ namespace Godot public struct Quat : IEquatable { /// - /// X component of the quaternion (imaginary `i` axis part). + /// X component of the quaternion (imaginary i axis part). /// Quaternion components should usually not be manipulated directly. /// public real_t x; /// - /// Y component of the quaternion (imaginary `j` axis part). + /// Y component of the quaternion (imaginary j axis part). /// Quaternion components should usually not be manipulated directly. /// public real_t y; /// - /// Z component of the quaternion (imaginary `k` axis part). + /// Z component of the quaternion (imaginary k axis part). /// Quaternion components should usually not be manipulated directly. /// public real_t z; @@ -52,7 +52,12 @@ namespace Godot /// /// Access quaternion components using their index. /// - /// `[0]` is equivalent to `.x`, `[1]` is equivalent to `.y`, `[2]` is equivalent to `.z`, `[3]` is equivalent to `.w`. + /// + /// [0] is equivalent to , + /// [1] is equivalent to , + /// [2] is equivalent to , + /// [3] is equivalent to . + /// public real_t this[int index] { get @@ -96,7 +101,8 @@ namespace Godot /// /// Returns the length (magnitude) of the quaternion. /// - /// Equivalent to `Mathf.Sqrt(LengthSquared)`. + /// + /// Equivalent to Mathf.Sqrt(LengthSquared). public real_t Length { get { return Mathf.Sqrt(LengthSquared); } @@ -107,14 +113,14 @@ namespace Godot /// This method runs faster than , so prefer it if /// you need to compare quaternions or need the squared length for some formula. /// - /// Equivalent to `Dot(this)`. + /// Equivalent to Dot(this). public real_t LengthSquared { get { return Dot(this); } } /// - /// Returns the angle between this quaternion and `to`. + /// Returns the angle between this quaternion and . /// This is the magnitude of the angle you would need to rotate /// by to get from one to the other. /// @@ -131,12 +137,12 @@ namespace Godot } /// - /// Performs a cubic spherical interpolation between quaternions `preA`, - /// this vector, `b`, and `postB`, by the given amount `t`. + /// Performs a cubic spherical interpolation between quaternions , this quaternion, + /// , and , by the given amount . /// /// The destination quaternion. /// A quaternion before this quaternion. - /// A quaternion after `b`. + /// A quaternion after . /// A value on the range of 0.0 to 1.0, representing the amount of interpolation. /// The interpolated quaternion. public Quat CubicSlerp(Quat b, Quat preA, Quat postB, real_t weight) @@ -195,7 +201,7 @@ namespace Godot /// /// Returns whether the quaternion is normalized or not. /// - /// A bool for whether the quaternion is normalized or not. + /// A for whether the quaternion is normalized or not. public bool IsNormalized() { return Mathf.Abs(LengthSquared - 1) <= Mathf.Epsilon; @@ -239,7 +245,7 @@ namespace Godot /// /// Returns the result of the spherical linear interpolation between - /// this quaternion and `to` by amount `weight`. + /// this quaternion and by amount . /// /// Note: Both quaternions must be normalized. /// @@ -311,7 +317,7 @@ namespace Godot /// /// Returns the result of the spherical linear interpolation between - /// this quaternion and `to` by amount `weight`, but without + /// this quaternion and by amount , but without /// checking if the rotation path is not bigger than 90 degrees. /// /// The destination quaternion for interpolation. Must be normalized. @@ -366,15 +372,15 @@ namespace Godot /// Equivalent to an identity matrix. If a vector is transformed by /// an identity quaternion, it will not change. /// - /// Equivalent to `new Quat(0, 0, 0, 1)`. + /// Equivalent to new Quat(0, 0, 0, 1). public static Quat Identity { get { return _identity; } } /// - /// Constructs a quaternion defined by the given values. + /// Constructs a defined by the given values. /// - /// X component of the quaternion (imaginary `i` axis part). - /// Y component of the quaternion (imaginary `j` axis part). - /// Z component of the quaternion (imaginary `k` axis part). + /// X component of the quaternion (imaginary i axis part). + /// Y component of the quaternion (imaginary j axis part). + /// Z component of the quaternion (imaginary k axis part). /// W component of the quaternion (real part). public Quat(real_t x, real_t y, real_t z, real_t w) { @@ -385,7 +391,7 @@ namespace Godot } /// - /// Constructs a quaternion from the given quaternion. + /// Constructs a from the given . /// /// The existing quaternion. public Quat(Quat q) @@ -394,21 +400,20 @@ namespace Godot } /// - /// Constructs a quaternion from the given . + /// Constructs a from the given . /// - /// The basis to construct from. + /// The to construct from. public Quat(Basis basis) { this = basis.Quat(); } /// - /// Constructs a quaternion that will perform a rotation specified by - /// Euler angles (in the YXZ convention: when decomposing, - /// first Z, then X, and Y last), + /// Constructs a that will perform a rotation specified by + /// Euler angles (in the YXZ convention: when decomposing, first Z, then X, and Y last), /// given in the vector format as (X angle, Y angle, Z angle). /// - /// + /// Euler angles that the quaternion will be rotated by. public Quat(Vector3 eulerYXZ) { real_t half_a1 = eulerYXZ.y * 0.5f; @@ -433,7 +438,7 @@ namespace Godot } /// - /// Constructs a quaternion that will rotate around the given axis + /// Constructs a that will rotate around the given axis /// by the specified angle. The axis must be a normalized vector. /// /// The axis to rotate around. Must be normalized. @@ -542,6 +547,11 @@ namespace Godot return !left.Equals(right); } + /// + /// Returns if this quaternion and are equal. + /// + /// The other object to compare. + /// Whether or not the quaternion and the other object are equal. public override bool Equals(object obj) { if (obj is Quat) @@ -552,14 +562,19 @@ namespace Godot return false; } + /// + /// Returns if this quaternion and are equal. + /// + /// The other quaternion to compare. + /// Whether or not the quaternions are equal. public bool Equals(Quat other) { return x == other.x && y == other.y && z == other.z && w == other.w; } /// - /// Returns true if this quaternion and `other` are approximately equal, by running - /// on each component. + /// Returns if this quaternion and are approximately equal, + /// by running on each component. /// /// The other quaternion to compare. /// Whether or not the quaternions are approximately equal. @@ -568,16 +583,28 @@ namespace Godot return Mathf.IsEqualApprox(x, other.x) && Mathf.IsEqualApprox(y, other.y) && Mathf.IsEqualApprox(z, other.z) && Mathf.IsEqualApprox(w, other.w); } + /// + /// Serves as the hash function for . + /// + /// A hash code for this quaternion. public override int GetHashCode() { return y.GetHashCode() ^ x.GetHashCode() ^ z.GetHashCode() ^ w.GetHashCode(); } + /// + /// Converts this to a string. + /// + /// A string representation of this quaternion. public override string ToString() { return String.Format("({0}, {1}, {2}, {3})", x.ToString(), y.ToString(), z.ToString(), w.ToString()); } + /// + /// Converts this to a string with the given . + /// + /// A string representation of this quaternion. public string ToString(string format) { return String.Format("({0}, {1}, {2}, {3})", x.ToString(format), y.ToString(format), z.ToString(format), w.ToString(format)); diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/RID.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/RID.cs index 94761531b12..f5c5d6fd0e0 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/RID.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/RID.cs @@ -3,6 +3,12 @@ using System.Runtime.CompilerServices; namespace Godot { + /// + /// The RID type is used to access the unique integer ID of a resource. + /// They are opaque, which means they do not grant access to the associated + /// resource by themselves. They are used by and with the low-level Server + /// classes such as . + /// public sealed partial class RID : IDisposable { private bool disposed = false; @@ -25,6 +31,9 @@ namespace Godot Dispose(false); } + /// + /// Disposes of this . + /// public void Dispose() { Dispose(true); @@ -50,6 +59,9 @@ namespace Godot this.ptr = ptr; } + /// + /// The pointer to the native instance of this . + /// public IntPtr NativeInstance { get { return ptr; } @@ -60,16 +72,27 @@ namespace Godot this.ptr = IntPtr.Zero; } + /// + /// Constructs a new for the given . + /// public RID(Object from) { this.ptr = godot_icall_RID_Ctor(Object.GetPtr(from)); } + /// + /// Returns the ID of the referenced resource. + /// + /// The ID of the referenced resource. public int GetId() { - return godot_icall_RID_get_id(RID.GetPtr(this)); + return godot_icall_RID_get_id(GetPtr(this)); } + /// + /// Converts this to a string. + /// + /// A string representation of this RID. public override string ToString() => "[RID]"; [MethodImpl(MethodImplOptions.InternalCall)] diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Rect2.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Rect2.cs index 42adc1db532..1b007cb55b9 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Rect2.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Rect2.cs @@ -20,7 +20,7 @@ namespace Godot private Vector2 _size; /// - /// Beginning corner. Typically has values lower than End. + /// Beginning corner. Typically has values lower than . /// /// Directly uses a private field. public Vector2 Position @@ -30,7 +30,7 @@ namespace Godot } /// - /// Size from Position to End. Typically all components are positive. + /// Size from to . Typically all components are positive. /// If the size is negative, you can use to fix it. /// /// Directly uses a private field. @@ -41,10 +41,13 @@ namespace Godot } /// - /// Ending corner. This is calculated as plus - /// . Setting this value will change the size. + /// Ending corner. This is calculated as plus . + /// Setting this value will change the size. /// - /// Getting is equivalent to `value = Position + Size`, setting is equivalent to `Size = value - Position`. + /// + /// Getting is equivalent to = + , + /// setting is equivalent to = - + /// public Vector2 End { get { return _position + _size; } @@ -52,7 +55,7 @@ namespace Godot } /// - /// The area of this rect. + /// The area of this . /// /// Equivalent to . public real_t Area @@ -61,10 +64,10 @@ namespace Godot } /// - /// Returns a Rect2 with equivalent position and size, modified so that + /// Returns a with equivalent position and size, modified so that /// the top-left corner is the origin and width and height are positive. /// - /// The modified rect. + /// The modified . public Rect2 Abs() { Vector2 end = End; @@ -73,10 +76,11 @@ namespace Godot } /// - /// Returns the intersection of this Rect2 and `b`. + /// Returns the intersection of this and . + /// If the rectangles do not intersect, an empty is returned. /// - /// The other rect. - /// The clipped rect. + /// The other . + /// The clipped . public Rect2 Clip(Rect2 b) { var newRect = b; @@ -99,10 +103,12 @@ namespace Godot } /// - /// Returns true if this Rect2 completely encloses another one. + /// Returns if this completely encloses another one. /// - /// The other rect that may be enclosed. - /// A bool for whether or not this rect encloses `b`. + /// The other that may be enclosed. + /// + /// A for whether or not this encloses . + /// public bool Encloses(Rect2 b) { return b._position.x >= _position.x && b._position.y >= _position.y && @@ -111,10 +117,10 @@ namespace Godot } /// - /// Returns this Rect2 expanded to include a given point. + /// Returns this expanded to include a given point. /// /// The point to include. - /// The expanded rect. + /// The expanded . public Rect2 Expand(Vector2 to) { var expanded = this; @@ -147,7 +153,7 @@ namespace Godot } /// - /// Returns the area of the Rect2. + /// Returns the area of the . /// /// The area. public real_t GetArea() @@ -156,10 +162,13 @@ namespace Godot } /// - /// Returns a copy of the Rect2 grown a given amount of units towards all the sides. + /// Returns a copy of the grown a given amount of units towards + /// all the sides. /// + /// + /// /// The amount to grow by. - /// The grown rect. + /// The grown . public Rect2 Grow(real_t by) { var g = this; @@ -173,13 +182,16 @@ namespace Godot } /// - /// Returns a copy of the Rect2 grown a given amount of units towards each direction individually. + /// Returns a copy of the grown a given amount of units towards + /// each direction individually. /// + /// + /// /// The amount to grow by on the left. /// The amount to grow by on the top. /// The amount to grow by on the right. /// The amount to grow by on the bottom. - /// The grown rect. + /// The grown . public Rect2 GrowIndividual(real_t left, real_t top, real_t right, real_t bottom) { var g = this; @@ -193,11 +205,14 @@ namespace Godot } /// - /// Returns a copy of the Rect2 grown a given amount of units towards the direction. + /// Returns a copy of the grown a given amount of units towards + /// the direction. /// + /// + /// /// The direction to grow in. /// The amount to grow by. - /// The grown rect. + /// The grown . public Rect2 GrowMargin(Margin margin, real_t by) { var g = this; @@ -211,19 +226,25 @@ namespace Godot } /// - /// Returns true if the Rect2 is flat or empty, or false otherwise. + /// Returns if the is flat or empty, + /// or otherwise. /// - /// A bool for whether or not the rect has area. + /// + /// A for whether or not the has area. + /// public bool HasNoArea() { return _size.x <= 0 || _size.y <= 0; } /// - /// Returns true if the Rect2 contains a point, or false otherwise. + /// Returns if the contains a point, + /// or otherwise. /// /// The point to check. - /// A bool for whether or not the rect contains `point`. + /// + /// A for whether or not the contains . + /// public bool HasPoint(Vector2 point) { if (point.x < _position.x) @@ -240,15 +261,16 @@ namespace Godot } /// - /// Returns true if the Rect2 overlaps with `b` + /// Returns if the overlaps with /// (i.e. they have at least one point in common). /// - /// If `includeBorders` is true, they will also be considered overlapping - /// if their borders touch, even without intersection. + /// If is , + /// they will also be considered overlapping if their borders touch, + /// even without intersection. /// - /// The other rect to check for intersections with. + /// The other to check for intersections with. /// Whether or not to consider borders. - /// A bool for whether or not they are intersecting. + /// A for whether or not they are intersecting. public bool Intersects(Rect2 b, bool includeBorders = false) { if (includeBorders) @@ -294,10 +316,10 @@ namespace Godot } /// - /// Returns a larger Rect2 that contains this Rect2 and `b`. + /// Returns a larger that contains this and . /// - /// The other rect. - /// The merged rect. + /// The other . + /// The merged . public Rect2 Merge(Rect2 b) { Rect2 newRect; @@ -314,7 +336,7 @@ namespace Godot } /// - /// Constructs a Rect2 from a position and size. + /// Constructs a from a position and size. /// /// The position. /// The size. @@ -325,7 +347,7 @@ namespace Godot } /// - /// Constructs a Rect2 from a position, width, and height. + /// Constructs a from a position, width, and height. /// /// The position. /// The width. @@ -337,7 +359,7 @@ namespace Godot } /// - /// Constructs a Rect2 from x, y, and size. + /// Constructs a from x, y, and size. /// /// The position's X coordinate. /// The position's Y coordinate. @@ -349,7 +371,7 @@ namespace Godot } /// - /// Constructs a Rect2 from x, y, width, and height. + /// Constructs a from x, y, width, and height. /// /// The position's X coordinate. /// The position's Y coordinate. @@ -371,6 +393,11 @@ namespace Godot return !left.Equals(right); } + /// + /// Returns if this rect and are equal. + /// + /// The other object to compare. + /// Whether or not the rect and the other object are equal. public override bool Equals(object obj) { if (obj is Rect2) @@ -381,14 +408,19 @@ namespace Godot return false; } + /// + /// Returns if this rect and are equal. + /// + /// The other rect to compare. + /// Whether or not the rects are equal. public bool Equals(Rect2 other) { return _position.Equals(other._position) && _size.Equals(other._size); } /// - /// Returns true if this rect and `other` are approximately equal, by running - /// on each component. + /// Returns if this rect and are approximately equal, + /// by running on each component. /// /// The other rect to compare. /// Whether or not the rects are approximately equal. @@ -397,11 +429,19 @@ namespace Godot return _position.IsEqualApprox(other._position) && _size.IsEqualApprox(other.Size); } + /// + /// Serves as the hash function for . + /// + /// A hash code for this rect. public override int GetHashCode() { return _position.GetHashCode() ^ _size.GetHashCode(); } + /// + /// Converts this to a string. + /// + /// A string representation of this rect. public override string ToString() { return String.Format("({0}, {1})", new object[] @@ -411,6 +451,10 @@ namespace Godot }); } + /// + /// Converts this to a string with the given . + /// + /// A string representation of this rect. public string ToString(string format) { return String.Format("({0}, {1})", new object[] diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/StringExtensions.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/StringExtensions.cs index 34da29bdf50..2f1d4f855d9 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/StringExtensions.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/StringExtensions.cs @@ -8,6 +8,9 @@ using System.Text.RegularExpressions; namespace Godot { + /// + /// Extension methods to manipulate strings. + /// public static class StringExtensions { private static int GetSliceCount(this string instance, string splitter) @@ -64,6 +67,11 @@ namespace Godot /// /// If the string is a path to a file, return the path to the file without the extension. /// + /// + /// + /// + /// The path to a file. + /// The path to the file without the extension. public static string BaseName(this string instance) { int index = instance.LastIndexOf('.'); @@ -75,16 +83,22 @@ namespace Godot } /// - /// Return if the strings begins with the given string. + /// Returns if the strings begins + /// with the given string . /// + /// The string to check. + /// The beginning string. + /// If the string begins with the given string. public static bool BeginsWith(this string instance, string text) { return instance.StartsWith(text); } /// - /// Return the bigrams (pairs of consecutive letters) of this string. + /// Returns the bigrams (pairs of consecutive letters) of this string. /// + /// The string that will be used. + /// The bigrams of this string. public static string[] Bigrams(this string instance) { var b = new string[instance.Length - 1]; @@ -99,8 +113,8 @@ namespace Godot /// /// Converts a string containing a binary number into an integer. - /// Binary strings can either be prefixed with `0b` or not, - /// and they can also start with a `-` before the optional prefix. + /// Binary strings can either be prefixed with 0b or not, + /// and they can also start with a - before the optional prefix. /// /// The string to convert. /// The converted string. @@ -128,8 +142,14 @@ namespace Godot } /// - /// Return the amount of substrings in string. + /// Returns the amount of substrings in the string. /// + /// The string where the substring will be searched. + /// The substring that will be counted. + /// If the search is case sensitive. + /// Index to start searching from. + /// Index to stop searching at. + /// Amount of substrings in the string. public static int Count(this string instance, string what, bool caseSensitive = true, int from = 0, int to = 0) { if (what.Length == 0) @@ -188,8 +208,10 @@ namespace Godot } /// - /// Return a copy of the string with special characters escaped using the C language standard. + /// Returns a copy of the string with special characters escaped using the C language standard. /// + /// The string to escape. + /// The escaped string. public static string CEscape(this string instance) { var sb = new StringBuilder(string.Copy(instance)); @@ -210,9 +232,11 @@ namespace Godot } /// - /// Return a copy of the string with escaped characters replaced by their meanings + /// Returns a copy of the string with escaped characters replaced by their meanings /// according to the C language standard. /// + /// The string to unescape. + /// The unescaped string. public static string CUnescape(this string instance) { var sb = new StringBuilder(string.Copy(instance)); @@ -233,11 +257,13 @@ namespace Godot } /// - /// Change the case of some letters. Replace underscores with spaces, convert all letters + /// Changes the case of some letters. Replace underscores with spaces, convert all letters /// to lowercase then capitalize first and every letter following the space character. /// For capitalize camelCase mixed_with_underscores it will return /// Capitalize Camelcase Mixed With Underscores. /// + /// The string to capitalize. + /// The capitalized string. public static string Capitalize(this string instance) { string aux = instance.Replace("_", " ").ToLower(); @@ -259,16 +285,27 @@ namespace Godot } /// - /// Perform a case-sensitive comparison to another string, return -1 if less, 0 if equal and +1 if greater. + /// Performs a case-sensitive comparison to another string, return -1 if less, 0 if equal and +1 if greater. /// + /// + /// + /// The string to compare. + /// The other string to compare. + /// -1 if less, 0 if equal and +1 if greater. public static int CasecmpTo(this string instance, string to) { return instance.CompareTo(to, caseSensitive: true); } /// - /// Perform a comparison to another string, return -1 if less, 0 if equal and +1 if greater. + /// Performs a comparison to another string, return -1 if less, 0 if equal and +1 if greater. /// + /// The string to compare. + /// The other string to compare. + /// + /// If , the comparison will be case sensitive. + /// + /// -1 if less, 0 if equal and +1 if greater. public static int CompareTo(this string instance, string to, bool caseSensitive = true) { if (instance.Empty()) @@ -321,7 +358,7 @@ namespace Godot } /// - /// Return if the string is empty. + /// Returns if the string is empty. /// public static bool Empty(this string instance) { @@ -329,8 +366,12 @@ namespace Godot } /// - /// Return if the strings ends with the given string. + /// Returns if the strings ends + /// with the given string . /// + /// The string to check. + /// The ending string. + /// If the string ends with the given string. public static bool EndsWith(this string instance, string text) { return instance.EndsWith(text); @@ -339,14 +380,36 @@ namespace Godot /// /// Erase characters from the string starting from . /// + /// The string to modify. + /// Starting position from which to erase. + /// Amount of characters to erase. public static void Erase(this StringBuilder instance, int pos, int chars) { instance.Remove(pos, chars); } /// - /// If the string is a path to a file, return the extension. + /// Returns the extension without the leading period character (.) + /// if the string is a valid file name or path. If the string does not contain + /// an extension, returns an empty string instead. /// + /// + /// + /// GD.Print("/path/to/file.txt".GetExtension()) // "txt" + /// GD.Print("file.txt".GetExtension()) // "txt" + /// GD.Print("file.sample.txt".GetExtension()) // "txt" + /// GD.Print(".txt".GetExtension()) // "txt" + /// GD.Print("file.txt.".GetExtension()) // "" (empty string) + /// GD.Print("file.txt..".GetExtension()) // "" (empty string) + /// GD.Print("txt".GetExtension()) // "" (empty string) + /// GD.Print("".GetExtension()) // "" (empty string) + /// + /// + /// + /// + /// + /// The path to a file. + /// The extension of the file or an empty string. public static string Extension(this string instance) { int pos = instance.FindLast("."); @@ -360,6 +423,10 @@ namespace Godot /// /// Find the first occurrence of a substring. Optionally, the search starting position can be passed. /// + /// The string that will be searched. + /// The substring to find. + /// The search starting position. + /// If , the search is case sensitive. /// The starting position of the substring, or -1 if not found. public static int Find(this string instance, string what, int from = 0, bool caseSensitive = true) { @@ -369,6 +436,14 @@ namespace Godot /// /// Find the first occurrence of a char. Optionally, the search starting position can be passed. /// + /// + /// + /// + /// + /// The string that will be searched. + /// The substring to find. + /// The search starting position. + /// If , the search is case sensitive. /// The first instance of the char, or -1 if not found. public static int Find(this string instance, char what, int from = 0, bool caseSensitive = true) { @@ -378,6 +453,13 @@ namespace Godot } /// Find the last occurrence of a substring. + /// + /// + /// + /// + /// The string that will be searched. + /// The substring to find. + /// If , the search is case sensitive. /// The starting position of the substring, or -1 if not found. public static int FindLast(this string instance, string what, bool caseSensitive = true) { @@ -385,6 +467,14 @@ namespace Godot } /// Find the last occurrence of a substring specifying the search starting position. + /// + /// + /// + /// + /// The string that will be searched. + /// The substring to find. + /// The search starting position. + /// If , the search is case sensitive. /// The starting position of the substring, or -1 if not found. public static int FindLast(this string instance, string what, int from, bool caseSensitive = true) { @@ -395,6 +485,13 @@ namespace Godot /// Find the first occurrence of a substring but search as case-insensitive. /// Optionally, the search starting position can be passed. /// + /// + /// + /// + /// + /// The string that will be searched. + /// The substring to find. + /// The search starting position. /// The starting position of the substring, or -1 if not found. public static int FindN(this string instance, string what, int from = 0) { @@ -404,6 +501,11 @@ namespace Godot /// /// If the string is a path to a file, return the base directory. /// + /// + /// + /// + /// The path to a file. + /// The base directory. public static string GetBaseDir(this string instance) { int basepos = instance.Find("://"); @@ -441,6 +543,11 @@ namespace Godot /// /// If the string is a path to a file, return the file and ignore the base directory. /// + /// + /// + /// + /// The path to a file. + /// The file name. public static string GetFile(this string instance) { int sep = Mathf.Max(instance.FindLast("/"), instance.FindLast("\\")); @@ -483,6 +590,8 @@ namespace Godot /// /// Hash the string and return a 32 bits unsigned integer. /// + /// The string to hash. + /// The calculated hash of the string. public static uint Hash(this string instance) { uint hash = 5381; @@ -544,8 +653,8 @@ namespace Godot /// /// Converts a string containing a hexadecimal number into an integer. - /// Hexadecimal strings can either be prefixed with `0x` or not, - /// and they can also start with a `-` before the optional prefix. + /// Hexadecimal strings can either be prefixed with 0x or not, + /// and they can also start with a - before the optional prefix. /// /// The string to convert. /// The converted string. @@ -573,16 +682,28 @@ namespace Godot } /// - /// Insert a substring at a given position. + /// Inserts a substring at a given position. /// + /// The string to modify. + /// Position at which to insert the substring. + /// Substring to insert. + /// + /// The string with inserted at the given + /// position . + /// public static string Insert(this string instance, int pos, string what) { return instance.Insert(pos, what); } /// - /// If the string is a path to a file or directory, return if the path is absolute. + /// Returns if the string is a path to a file or + /// directory and its startign point is explicitly defined. This includes + /// res://, user://, C:\, /, etc. /// + /// + /// The string to check. + /// If the string is an absolute path. public static bool IsAbsPath(this string instance) { if (string.IsNullOrEmpty(instance)) @@ -594,8 +715,14 @@ namespace Godot } /// - /// If the string is a path to a file or directory, return if the path is relative. + /// Returns if the string is a path to a file or + /// directory and its starting point is implicitly defined within the + /// context it is being used. The starting point may refer to the current + /// directory (./), or the current . /// + /// + /// The string to check. + /// If the string is a relative path. public static bool IsRelPath(this string instance) { return !IsAbsPath(instance); @@ -604,6 +731,11 @@ namespace Godot /// /// Check whether this string is a subsequence of the given string. /// + /// + /// The subsequence to search. + /// The string that contains the subsequence. + /// If , the check is case sensitive. + /// If the string is a subsequence of the given string. public static bool IsSubsequenceOf(this string instance, string text, bool caseSensitive = true) { int len = instance.Length; @@ -647,6 +779,10 @@ namespace Godot /// /// Check whether this string is a subsequence of the given string, ignoring case differences. /// + /// + /// The subsequence to search. + /// The string that contains the subsequence. + /// If the string is a subsequence of the given string. public static bool IsSubsequenceOfI(this string instance, string text) { return instance.IsSubsequenceOf(text, caseSensitive: false); @@ -655,6 +791,8 @@ namespace Godot /// /// Check whether the string contains a valid . /// + /// The string to check. + /// If the string contains a valid floating point number. public static bool IsValidFloat(this string instance) { float f; @@ -664,6 +802,8 @@ namespace Godot /// /// Check whether the string contains a valid color in HTML notation. /// + /// The string to check. + /// If the string contains a valid HTML color. public static bool IsValidHtmlColor(this string instance) { return Color.HtmlIsValid(instance); @@ -674,6 +814,8 @@ namespace Godot /// programming languages, a valid identifier may contain only letters, /// digits and underscores (_) and the first character may not be a digit. /// + /// The string to check. + /// If the string contains a valid identifier. public static bool IsValidIdentifier(this string instance) { int len = instance.Length; @@ -704,6 +846,8 @@ namespace Godot /// /// Check whether the string contains a valid integer. /// + /// The string to check. + /// If the string contains a valid integer. public static bool IsValidInteger(this string instance) { int f; @@ -713,6 +857,8 @@ namespace Godot /// /// Check whether the string contains a valid IP address. /// + /// The string to check. + /// If the string contains a valid IP address. public static bool IsValidIPAddress(this string instance) { // TODO: Support IPv6 addresses @@ -736,8 +882,10 @@ namespace Godot } /// - /// Return a copy of the string with special characters escaped using the JSON standard. + /// Returns a copy of the string with special characters escaped using the JSON standard. /// + /// The string to escape. + /// The escaped string. public static string JSONEscape(this string instance) { var sb = new StringBuilder(string.Copy(instance)); @@ -755,8 +903,12 @@ namespace Godot } /// - /// Return an amount of characters from the left of the string. + /// Returns an amount of characters from the left of the string. /// + /// + /// The original string. + /// The position in the string where the left side ends. + /// The left side of the string from the given position. public static string Left(this string instance, int pos) { if (pos <= 0) @@ -769,8 +921,10 @@ namespace Godot } /// - /// Return the length of the string in characters. + /// Returns the length of the string in characters. /// + /// The string to check. + /// The length of the string. public static int Length(this string instance) { return instance.Length; @@ -779,6 +933,7 @@ namespace Godot /// /// Returns a copy of the string with characters removed from the left. /// + /// /// The string to remove characters from. /// The characters to be removed. /// A copy of the string with characters removed from the left. @@ -807,6 +962,12 @@ namespace Godot /// Do a simple expression match, where '*' matches zero or more /// arbitrary characters and '?' matches any single character except '.'. /// + /// The string to check. + /// Expression to check. + /// + /// If , the check will be case sensitive. + /// + /// If the expression has any matches. private static bool ExprMatch(this string instance, string expr, bool caseSensitive) { // case '\0': @@ -832,6 +993,13 @@ namespace Godot /// Do a simple case sensitive expression match, using ? and * wildcards /// (see ). /// + /// + /// The string to check. + /// Expression to check. + /// + /// If , the check will be case sensitive. + /// + /// If the expression has any matches. public static bool Match(this string instance, string expr, bool caseSensitive = true) { if (instance.Length == 0 || expr.Length == 0) @@ -844,6 +1012,10 @@ namespace Godot /// Do a simple case insensitive expression match, using ? and * wildcards /// (see ). /// + /// + /// The string to check. + /// Expression to check. + /// If the expression has any matches. public static bool MatchN(this string instance, string expr) { if (instance.Length == 0 || expr.Length == 0) @@ -853,8 +1025,11 @@ namespace Godot } /// - /// Return the MD5 hash of the string as an array of bytes. + /// Returns the MD5 hash of the string as an array of bytes. /// + /// + /// The string to hash. + /// The MD5 hash of the string. public static byte[] MD5Buffer(this string instance) { return godot_icall_String_md5_buffer(instance); @@ -864,8 +1039,11 @@ namespace Godot internal extern static byte[] godot_icall_String_md5_buffer(string str); /// - /// Return the MD5 hash of the string as a string. + /// Returns the MD5 hash of the string as a string. /// + /// + /// The string to hash. + /// The MD5 hash of the string. public static string MD5Text(this string instance) { return godot_icall_String_md5_text(instance); @@ -877,22 +1055,35 @@ namespace Godot /// /// Perform a case-insensitive comparison to another string, return -1 if less, 0 if equal and +1 if greater. /// + /// + /// + /// The string to compare. + /// The other string to compare. + /// -1 if less, 0 if equal and +1 if greater. public static int NocasecmpTo(this string instance, string to) { return instance.CompareTo(to, caseSensitive: false); } /// - /// Return the character code at position . + /// Returns the character code at position . /// + /// The string to check. + /// The position int the string for the character to check. + /// The character code. public static int OrdAt(this string instance, int at) { return instance[at]; } /// - /// Format a number to have an exact number of after the decimal point. + /// Format a number to have an exact number of + /// after the decimal point. /// + /// + /// The string to pad. + /// Amount of digits after the decimal point. + /// The string padded with zeroes. public static string PadDecimals(this string instance, int digits) { int c = instance.Find("."); @@ -927,8 +1118,13 @@ namespace Godot } /// - /// Format a number to have an exact number of before the decimal point. + /// Format a number to have an exact number of + /// before the decimal point. /// + /// + /// The string to pad. + /// Amount of digits before the decimal point. + /// The string padded with zeroes. public static string PadZeros(this string instance, int digits) { string s = instance; @@ -968,17 +1164,23 @@ namespace Godot } /// - /// Percent-encode a string. This is meant to encode parameters in a URL when sending a HTTP GET request and bodies of form-urlencoded POST request. + /// Percent-encode a string. This is meant to encode parameters in a URL + /// when sending a HTTP GET request and bodies of form-urlencoded POST request. /// + /// public static string PercentEncode(this string instance) { return Uri.EscapeDataString(instance); } /// - /// If the string is a path, this concatenates at the end of the string as a subpath. + /// If the string is a path, this concatenates + /// at the end of the string as a subpath. /// E.g. "this/is".PlusFile("path") == "this/is/path". /// + /// The path that will be concatenated. + /// File name to concatenate with the path. + /// The concatenated path with the given file name. public static string PlusFile(this string instance, string file) { if (instance.Length > 0 && instance[instance.Length - 1] == '/') @@ -989,6 +1191,11 @@ namespace Godot /// /// Replace occurrences of a substring for different ones inside the string. /// + /// + /// The string to modify. + /// The substring to be replaced in the string. + /// The substring that replaces . + /// The string with the substring occurrences replaced. public static string Replace(this string instance, string what, string forwhat) { return instance.Replace(what, forwhat); @@ -997,6 +1204,11 @@ namespace Godot /// /// Replace occurrences of a substring for different ones inside the string, but search case-insensitive. /// + /// + /// The string to modify. + /// The substring to be replaced in the string. + /// The substring that replaces . + /// The string with the substring occurrences replaced. public static string ReplaceN(this string instance, string what, string forwhat) { return Regex.Replace(instance, what, forwhat, RegexOptions.IgnoreCase); @@ -1005,6 +1217,11 @@ namespace Godot /// /// Perform a search for a substring, but start from the end of the string instead of the beginning. /// + /// + /// The string that will be searched. + /// The substring to search in the string. + /// The position at which to start searching. + /// The position at which the substring was found, or -1 if not found. public static int RFind(this string instance, string what, int from = -1) { return godot_icall_String_rfind(instance, what, from); @@ -1017,6 +1234,11 @@ namespace Godot /// Perform a search for a substring, but start from the end of the string instead of the beginning. /// Also search case-insensitive. /// + /// + /// The string that will be searched. + /// The substring to search in the string. + /// The position at which to start searching. + /// The position at which the substring was found, or -1 if not found. public static int RFindN(this string instance, string what, int from = -1) { return godot_icall_String_rfindn(instance, what, from); @@ -1026,8 +1248,12 @@ namespace Godot internal extern static int godot_icall_String_rfindn(string str, string what, int from); /// - /// Return the right side of the string from a given position. + /// Returns the right side of the string from a given position. /// + /// + /// The original string. + /// The position in the string from which the right side starts. + /// The right side of the string from the given position. public static string Right(this string instance, int pos) { if (pos >= instance.Length) @@ -1042,6 +1268,7 @@ namespace Godot /// /// Returns a copy of the string with characters removed from the right. /// + /// /// The string to remove characters from. /// The characters to be removed. /// A copy of the string with characters removed from the right. @@ -1066,6 +1293,12 @@ namespace Godot return instance.Substr(0, end + 1); } + /// + /// Returns the SHA-256 hash of the string as an array of bytes. + /// + /// + /// The string to hash. + /// The SHA-256 hash of the string. public static byte[] SHA256Buffer(this string instance) { return godot_icall_String_sha256_buffer(instance); @@ -1075,8 +1308,11 @@ namespace Godot internal extern static byte[] godot_icall_String_sha256_buffer(string str); /// - /// Return the SHA-256 hash of the string as a string. + /// Returns the SHA-256 hash of the string as a string. /// + /// + /// The string to hash. + /// The SHA-256 hash of the string. public static string SHA256Text(this string instance) { return godot_icall_String_sha256_text(instance); @@ -1086,9 +1322,12 @@ namespace Godot internal extern static string godot_icall_String_sha256_text(string str); /// - /// Return the similarity index of the text compared to this string. + /// Returns the similarity index of the text compared to this string. /// 1 means totally similar and 0 means totally dissimilar. /// + /// The string to compare. + /// The other string to compare. + /// The similarity index. public static float Similarity(this string instance, string text) { if (instance == text) @@ -1130,6 +1369,13 @@ namespace Godot /// Split the string by a divisor string, return an array of the substrings. /// Example "One,Two,Three" will return ["One","Two","Three"] if split by ",". /// + /// + /// The string to split. + /// The divisor string that splits the string. + /// + /// If , the array may include empty strings. + /// + /// The array of strings split from the string. public static string[] Split(this string instance, string divisor, bool allowEmpty = true) { return instance.Split(new[] { divisor }, allowEmpty ? StringSplitOptions.None : StringSplitOptions.RemoveEmptyEntries); @@ -1139,6 +1385,13 @@ namespace Godot /// Split the string in floats by using a divisor string, return an array of the substrings. /// Example "1,2.5,3" will return [1,2.5,3] if split by ",". /// + /// + /// The string to split. + /// The divisor string that splits the string. + /// + /// If , the array may include empty floats. + /// + /// The array of floats split from the string. public static float[] SplitFloats(this string instance, string divisor, bool allowEmpty = true) { var ret = new List(); @@ -1171,9 +1424,13 @@ namespace Godot }; /// - /// Return a copy of the string stripped of any non-printable character at the beginning and the end. + /// Returns a copy of the string stripped of any non-printable character at the beginning and the end. /// The optional arguments are used to toggle stripping on the left and right edges respectively. /// + /// The string to strip. + /// If the left side should be stripped. + /// If the right side should be stripped. + /// The string stripped of any non-printable characters. public static string StripEdges(this string instance, bool left = true, bool right = true) { if (left) @@ -1187,8 +1444,14 @@ namespace Godot } /// - /// Return part of the string from the position , with length . + /// Returns part of the string from the position , with length . /// + /// The string to slice. + /// The position in the string that the part starts from. + /// The length of the returned part. + /// + /// Part of the string from the position , with length . + /// public static string Substr(this string instance, int from, int len) { int max = instance.Length - from; @@ -1196,69 +1459,93 @@ namespace Godot } /// - /// Convert the String (which is a character array) to PoolByteArray (which is an array of bytes). + /// Converts the String (which is a character array) to PoolByteArray (which is an array of bytes). /// The conversion is speeded up in comparison to with the assumption /// that all the characters the String contains are only ASCII characters. /// + /// + /// The string to convert. + /// The string as ASCII encoded bytes. public static byte[] ToAscii(this string instance) { return Encoding.ASCII.GetBytes(instance); } /// - /// Convert a string, containing a decimal number, into a . + /// Converts a string, containing a decimal number, into a . /// + /// + /// The string to convert. + /// The number representation of the string. public static float ToFloat(this string instance) { return float.Parse(instance); } /// - /// Convert a string, containing an integer number, into an . + /// Converts a string, containing an integer number, into an . /// + /// + /// The string to convert. + /// The number representation of the string. public static int ToInt(this string instance) { return int.Parse(instance); } /// - /// Return the string converted to lowercase. + /// Returns the string converted to lowercase. /// + /// + /// The string to convert. + /// The string converted to lowercase. public static string ToLower(this string instance) { return instance.ToLower(); } /// - /// Return the string converted to uppercase. + /// Returns the string converted to uppercase. /// + /// + /// The string to convert. + /// The string converted to uppercase. public static string ToUpper(this string instance) { return instance.ToUpper(); } /// - /// Convert the String (which is an array of characters) to PoolByteArray (which is an array of bytes). + /// Converts the String (which is an array of characters) to PoolByteArray (which is an array of bytes). /// The conversion is a bit slower than , but supports all UTF-8 characters. /// Therefore, you should prefer this function over . /// + /// + /// The string to convert. + /// The string as UTF-8 encoded bytes. public static byte[] ToUTF8(this string instance) { return Encoding.UTF8.GetBytes(instance); } /// - /// Return a copy of the string with special characters escaped using the XML standard. + /// Returns a copy of the string with special characters escaped using the XML standard. /// + /// + /// The string to escape. + /// The escaped string. public static string XMLEscape(this string instance) { return SecurityElement.Escape(instance); } /// - /// Return a copy of the string with escaped characters replaced by their meanings + /// Returns a copy of the string with escaped characters replaced by their meanings /// according to the XML standard. /// + /// + /// The string to unescape. + /// The unescaped string. public static string XMLUnescape(this string instance) { return SecurityElement.FromString(instance).Text; diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform.cs index e8eef0f9ac5..974353054de 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform.cs @@ -28,12 +28,13 @@ namespace Godot public Basis basis; /// - /// The origin vector (column 3, the fourth column). Equivalent to array index `[3]`. + /// The origin vector (column 3, the fourth column). Equivalent to array index [3]. /// public Vector3 origin; /// - /// Access whole columns in the form of Vector3. The fourth column is the origin vector. + /// Access whole columns in the form of . + /// The fourth column is the vector. /// /// Which column vector. public Vector3 this[int column] @@ -77,7 +78,8 @@ namespace Godot } /// - /// Access matrix elements in column-major order. The fourth column is the origin vector. + /// Access matrix elements in column-major order. + /// The fourth column is the vector. /// /// Which column, the matrix horizontal position. /// Which row, the matrix vertical position. @@ -106,6 +108,7 @@ namespace Godot /// Returns the inverse of the transform, under the assumption that /// the transformation is composed of rotation, scaling, and translation. /// + /// /// The inverse transformation matrix. public Transform AffineInverse() { @@ -114,7 +117,7 @@ namespace Godot } /// - /// Interpolates this transform to the other `transform` by `weight`. + /// Interpolates this transform to the other by . /// /// The other transform. /// A value on the range of 0.0 to 1.0, representing the amount of interpolation. @@ -152,11 +155,11 @@ namespace Godot /// /// Returns a copy of the transform rotated such that its - /// -Z axis (forward) points towards the target position. + /// -Z axis (forward) points towards the position. /// - /// The transform will first be rotated around the given up vector, - /// and then fully aligned to the target by a further rotation around - /// an axis perpendicular to both the target and up vectors. + /// The transform will first be rotated around the given vector, + /// and then fully aligned to the by a further rotation around + /// an axis perpendicular to both the and vectors. /// /// Operations take place in global space. /// @@ -181,7 +184,7 @@ namespace Godot } /// - /// Rotates the transform around the given `axis` by `phi` (in radians), + /// Rotates the transform around the given by (in radians), /// using matrix multiplication. The axis must be a normalized vector. /// /// The axis to rotate around. Must be normalized. @@ -226,7 +229,7 @@ namespace Godot } /// - /// Translates the transform by the given `offset`, + /// Translates the transform by the given , /// relative to the transform's basis vectors. /// /// Unlike and , @@ -247,6 +250,7 @@ namespace Godot /// /// Returns a vector transformed (multiplied) by this transformation matrix. /// + /// /// A vector to transform. /// The transformed vector. public Vector3 Xform(Vector3 v) @@ -265,6 +269,7 @@ namespace Godot /// Note: This results in a multiplication by the inverse of the /// transformation matrix only if it represents a rotation-reflection. /// + /// /// A vector to inversely transform. /// The inversely transformed vector. public Vector3 XformInv(Vector3 v) @@ -287,25 +292,25 @@ namespace Godot /// /// The identity transform, with no translation, rotation, or scaling applied. - /// This is used as a replacement for `Transform()` in GDScript. - /// Do not use `new Transform()` with no arguments in C#, because it sets all values to zero. + /// This is used as a replacement for Transform() in GDScript. + /// Do not use new Transform() with no arguments in C#, because it sets all values to zero. /// - /// Equivalent to `new Transform(Vector3.Right, Vector3.Up, Vector3.Back, Vector3.Zero)`. + /// Equivalent to new Transform(Vector3.Right, Vector3.Up, Vector3.Back, Vector3.Zero). public static Transform Identity { get { return _identity; } } /// /// The transform that will flip something along the X axis. /// - /// Equivalent to `new Transform(Vector3.Left, Vector3.Up, Vector3.Back, Vector3.Zero)`. + /// Equivalent to new Transform(Vector3.Left, Vector3.Up, Vector3.Back, Vector3.Zero). public static Transform FlipX { get { return _flipX; } } /// /// The transform that will flip something along the Y axis. /// - /// Equivalent to `new Transform(Vector3.Right, Vector3.Down, Vector3.Back, Vector3.Zero)`. + /// Equivalent to new Transform(Vector3.Right, Vector3.Down, Vector3.Back, Vector3.Zero). public static Transform FlipY { get { return _flipY; } } /// /// The transform that will flip something along the Z axis. /// - /// Equivalent to `new Transform(Vector3.Right, Vector3.Up, Vector3.Forward, Vector3.Zero)`. + /// Equivalent to new Transform(Vector3.Right, Vector3.Up, Vector3.Forward, Vector3.Zero). public static Transform FlipZ { get { return _flipZ; } } /// @@ -322,9 +327,10 @@ namespace Godot } /// - /// Constructs a transformation matrix from the given quaternion and origin vector. + /// Constructs a transformation matrix from the given + /// and vector. /// - /// The to create the basis from. + /// The to create the basis from. /// The origin vector, or column index 3. public Transform(Quat quat, Vector3 origin) { @@ -333,9 +339,10 @@ namespace Godot } /// - /// Constructs a transformation matrix from the given basis and origin vector. + /// Constructs a transformation matrix from the given and + /// vector. /// - /// The to create the basis from. + /// The to create the basis from. /// The origin vector, or column index 3. public Transform(Basis basis, Vector3 origin) { @@ -360,6 +367,11 @@ namespace Godot return !left.Equals(right); } + /// + /// Returns if this transform and are equal. + /// + /// The other object to compare. + /// Whether or not the transform and the other object are equal. public override bool Equals(object obj) { if (obj is Transform) @@ -370,14 +382,19 @@ namespace Godot return false; } + /// + /// Returns if this transform and are equal. + /// + /// The other transform to compare. + /// Whether or not the matrices are equal. public bool Equals(Transform other) { return basis.Equals(other.basis) && origin.Equals(other.origin); } /// - /// Returns true if this transform and `other` are approximately equal, by running - /// on each component. + /// Returns if this transform and are approximately equal, + /// by running on each component. /// /// The other transform to compare. /// Whether or not the matrices are approximately equal. @@ -386,11 +403,19 @@ namespace Godot return basis.IsEqualApprox(other.basis) && origin.IsEqualApprox(other.origin); } + /// + /// Serves as the hash function for . + /// + /// A hash code for this transform. public override int GetHashCode() { return basis.GetHashCode() ^ origin.GetHashCode(); } + /// + /// Converts this to a string. + /// + /// A string representation of this transform. public override string ToString() { return String.Format("{0} - {1}", new object[] @@ -400,6 +425,10 @@ namespace Godot }); } + /// + /// Converts this to a string with the given . + /// + /// A string representation of this transform. public string ToString(string format) { return String.Format("{0} - {1}", new object[] diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform2D.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform2D.cs index c850ec39b21..f3f71beb86f 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform2D.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Transform2D.cs @@ -21,18 +21,18 @@ namespace Godot public struct Transform2D : IEquatable { /// - /// The basis matrix's X vector (column 0). Equivalent to array index `[0]`. + /// The basis matrix's X vector (column 0). Equivalent to array index [0]. /// /// public Vector2 x; /// - /// The basis matrix's Y vector (column 1). Equivalent to array index `[1]`. + /// The basis matrix's Y vector (column 1). Equivalent to array index [1]. /// public Vector2 y; /// - /// The origin vector (column 2, the third column). Equivalent to array index `[2]`. + /// The origin vector (column 2, the third column). Equivalent to array index [2]. /// The origin vector represents translation. /// public Vector2 origin; @@ -77,7 +77,8 @@ namespace Godot } /// - /// Access whole columns in the form of Vector2. The third column is the origin vector. + /// Access whole columns in the form of . + /// The third column is the vector. /// /// Which column vector. public Vector2 this[int column] @@ -116,7 +117,8 @@ namespace Godot } /// - /// Access matrix elements in column-major order. The third column is the origin vector. + /// Access matrix elements in column-major order. + /// The third column is the vector. /// /// Which column, the matrix horizontal position. /// Which row, the matrix vertical position. @@ -138,6 +140,7 @@ namespace Godot /// Returns the inverse of the transform, under the assumption that /// the transformation is composed of rotation, scaling, and translation. /// + /// /// The inverse transformation matrix. public Transform2D AffineInverse() { @@ -178,8 +181,9 @@ namespace Godot /// /// Returns a vector transformed (multiplied) by the basis matrix. - /// This method does not account for translation (the origin vector). + /// This method does not account for translation (the vector). /// + /// /// A vector to transform. /// The transformed vector. public Vector2 BasisXform(Vector2 v) @@ -189,11 +193,12 @@ namespace Godot /// /// Returns a vector transformed (multiplied) by the inverse basis matrix. - /// This method does not account for translation (the origin vector). + /// This method does not account for translation (the vector). /// /// Note: This results in a multiplication by the inverse of the /// basis matrix only if it represents a rotation-reflection. /// + /// /// A vector to inversely transform. /// The inversely transformed vector. public Vector2 BasisXformInv(Vector2 v) @@ -202,7 +207,7 @@ namespace Godot } /// - /// Interpolates this transform to the other `transform` by `weight`. + /// Interpolates this transform to the other by . /// /// The other transform. /// A value on the range of 0.0 to 1.0, representing the amount of interpolation. @@ -293,7 +298,7 @@ namespace Godot } /// - /// Rotates the transform by `phi` (in radians), using matrix multiplication. + /// Rotates the transform by (in radians), using matrix multiplication. /// /// The angle to rotate, in radians. /// The rotated transformation matrix. @@ -335,7 +340,7 @@ namespace Godot } /// - /// Translates the transform by the given `offset`, + /// Translates the transform by the given , /// relative to the transform's basis vectors. /// /// Unlike and , @@ -353,6 +358,7 @@ namespace Godot /// /// Returns a vector transformed (multiplied) by this transformation matrix. /// + /// /// A vector to transform. /// The transformed vector. public Vector2 Xform(Vector2 v) @@ -363,6 +369,7 @@ namespace Godot /// /// Returns a vector transformed (multiplied) by the inverse transformation matrix. /// + /// /// A vector to inversely transform. /// The inversely transformed vector. public Vector2 XformInv(Vector2 v) @@ -378,20 +385,20 @@ namespace Godot /// /// The identity transform, with no translation, rotation, or scaling applied. - /// This is used as a replacement for `Transform2D()` in GDScript. - /// Do not use `new Transform2D()` with no arguments in C#, because it sets all values to zero. + /// This is used as a replacement for Transform2D() in GDScript. + /// Do not use new Transform2D() with no arguments in C#, because it sets all values to zero. /// - /// Equivalent to `new Transform2D(Vector2.Right, Vector2.Down, Vector2.Zero)`. + /// Equivalent to new Transform2D(Vector2.Right, Vector2.Down, Vector2.Zero). public static Transform2D Identity { get { return _identity; } } /// /// The transform that will flip something along the X axis. /// - /// Equivalent to `new Transform2D(Vector2.Left, Vector2.Down, Vector2.Zero)`. + /// Equivalent to new Transform2D(Vector2.Left, Vector2.Down, Vector2.Zero). public static Transform2D FlipX { get { return _flipX; } } /// /// The transform that will flip something along the Y axis. /// - /// Equivalent to `new Transform2D(Vector2.Right, Vector2.Up, Vector2.Zero)`. + /// Equivalent to new Transform2D(Vector2.Right, Vector2.Up, Vector2.Zero). public static Transform2D FlipY { get { return _flipY; } } /// @@ -411,12 +418,12 @@ namespace Godot /// Constructs a transformation matrix from the given components. /// Arguments are named such that xy is equal to calling x.y /// - /// The X component of the X column vector, accessed via `t.x.x` or `[0][0]` - /// The Y component of the X column vector, accessed via `t.x.y` or `[0][1]` - /// The X component of the Y column vector, accessed via `t.y.x` or `[1][0]` - /// The Y component of the Y column vector, accessed via `t.y.y` or `[1][1]` - /// The X component of the origin vector, accessed via `t.origin.x` or `[2][0]` - /// The Y component of the origin vector, accessed via `t.origin.y` or `[2][1]` + /// The X component of the X column vector, accessed via t.x.x or [0][0] + /// The Y component of the X column vector, accessed via t.x.y or [0][1] + /// The X component of the Y column vector, accessed via t.y.x or [1][0] + /// The Y component of the Y column vector, accessed via t.y.y or [1][1] + /// The X component of the origin vector, accessed via t.origin.x or [2][0] + /// The Y component of the origin vector, accessed via t.origin.y or [2][1] public Transform2D(real_t xx, real_t xy, real_t yx, real_t yy, real_t ox, real_t oy) { x = new Vector2(xx, xy); @@ -425,16 +432,17 @@ namespace Godot } /// - /// Constructs a transformation matrix from a rotation value and origin vector. + /// Constructs a transformation matrix from a value and + /// vector. /// - /// The rotation of the new transform, in radians. - /// The origin vector, or column index 2. - public Transform2D(real_t rot, Vector2 pos) + /// The rotation of the new transform, in radians. + /// The origin vector, or column index 2. + public Transform2D(real_t rotation, Vector2 origin) { - x.x = y.y = Mathf.Cos(rot); - x.y = y.x = Mathf.Sin(rot); + x.x = y.y = Mathf.Cos(rotation); + x.y = y.x = Mathf.Sin(rotation); y.x *= -1; - origin = pos; + this.origin = origin; } public static Transform2D operator *(Transform2D left, Transform2D right) @@ -464,19 +472,29 @@ namespace Godot return !left.Equals(right); } + /// + /// Returns if this transform and are equal. + /// + /// The other object to compare. + /// Whether or not the transform and the other object are equal. public override bool Equals(object obj) { return obj is Transform2D transform2D && Equals(transform2D); } + /// + /// Returns if this transform and are equal. + /// + /// The other transform to compare. + /// Whether or not the matrices are equal. public bool Equals(Transform2D other) { return x.Equals(other.x) && y.Equals(other.y) && origin.Equals(other.origin); } /// - /// Returns true if this transform and `other` are approximately equal, by running - /// on each component. + /// Returns if this transform and are approximately equal, + /// by running on each component. /// /// The other transform to compare. /// Whether or not the matrices are approximately equal. @@ -485,11 +503,19 @@ namespace Godot return x.IsEqualApprox(other.x) && y.IsEqualApprox(other.y) && origin.IsEqualApprox(other.origin); } + /// + /// Serves as the hash function for . + /// + /// A hash code for this transform. public override int GetHashCode() { return x.GetHashCode() ^ y.GetHashCode() ^ origin.GetHashCode(); } + /// + /// Converts this to a string. + /// + /// A string representation of this transform. public override string ToString() { return String.Format("({0}, {1}, {2})", new object[] @@ -500,6 +526,10 @@ namespace Godot }); } + /// + /// Converts this to a string with the given . + /// + /// A string representation of this transform. public string ToString(string format) { return String.Format("({0}, {1}, {2})", new object[] diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/UnhandledExceptionArgs.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/UnhandledExceptionArgs.cs index be016745689..eae8927ceb9 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/UnhandledExceptionArgs.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/UnhandledExceptionArgs.cs @@ -8,7 +8,7 @@ namespace Godot public class UnhandledExceptionArgs { /// - /// Exception object + /// Exception object. /// public Exception Exception { get; private set; } diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Vector2.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Vector2.cs index cb326484dac..1ed946b98d8 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Vector2.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Vector2.cs @@ -21,23 +21,35 @@ namespace Godot /// public enum Axis { + /// + /// The vector's X axis. + /// X = 0, + /// + /// The vector's Y axis. + /// Y } /// - /// The vector's X component. Also accessible by using the index position `[0]`. + /// The vector's X component. Also accessible by using the index position [0]. /// public real_t x; /// - /// The vector's Y component. Also accessible by using the index position `[1]`. + /// The vector's Y component. Also accessible by using the index position [1]. /// public real_t y; /// /// Access vector components using their index. /// - /// `[0]` is equivalent to `.x`, `[1]` is equivalent to `.y`. + /// + /// Thrown when the given the is not 0 or 1. + /// + /// + /// [0] is equivalent to , + /// [1] is equivalent to . + /// public real_t this[int index] { get @@ -97,7 +109,7 @@ namespace Godot /// Returns this vector's angle with respect to the X axis, or (1, 0) vector, in radians. /// /// Equivalent to the result of when - /// called with the vector's `y` and `x` as parameters: `Mathf.Atan2(v.y, v.x)`. + /// called with the vector's and as parameters: Mathf.Atan2(v.y, v.x). /// /// The angle of this vector, in radians. public real_t Angle() @@ -126,9 +138,9 @@ namespace Godot } /// - /// Returns the aspect ratio of this vector, the ratio of `x` to `y`. + /// Returns the aspect ratio of this vector, the ratio of to . /// - /// The `x` component divided by the `y` component. + /// The component divided by the component. public real_t Aspect() { return x / y; @@ -154,7 +166,7 @@ namespace Godot } /// - /// Returns the vector with a maximum length by limiting its length to `length`. + /// Returns the vector with a maximum length by limiting its length to . /// /// The length to limit to. /// The vector with its length limited. @@ -173,7 +185,7 @@ namespace Godot } /// - /// Returns the cross product of this vector and `b`. + /// Returns the cross product of this vector and . /// /// The other vector. /// The cross product value. @@ -183,11 +195,12 @@ namespace Godot } /// - /// Performs a cubic interpolation between vectors `preA`, this vector, `b`, and `postB`, by the given amount `t`. + /// Performs a cubic interpolation between vectors , this vector, + /// , and , by the given amount . /// /// The destination vector. /// A vector before this vector. - /// A vector after `b`. + /// A vector after . /// A value on the range of 0.0 to 1.0, representing the amount of interpolation. /// The interpolated vector. public Vector2 CubicInterpolate(Vector2 b, Vector2 preA, Vector2 postB, real_t weight) @@ -208,17 +221,17 @@ namespace Godot } /// - /// Returns the normalized vector pointing from this vector to `b`. + /// Returns the normalized vector pointing from this vector to . /// /// The other vector to point towards. - /// The direction from this vector to `b`. + /// The direction from this vector to . public Vector2 DirectionTo(Vector2 b) { return new Vector2(b.x - x, b.y - y).Normalized(); } /// - /// Returns the squared distance between this vector and `to`. + /// Returns the squared distance between this vector and . /// This method runs faster than , so prefer it if /// you need to compare vectors or need the squared distance for some formula. /// @@ -230,7 +243,7 @@ namespace Godot } /// - /// Returns the distance between this vector and `to`. + /// Returns the distance between this vector and . /// /// The other vector to use. /// The distance between the two vectors. @@ -240,7 +253,7 @@ namespace Godot } /// - /// Returns the dot product of this vector and `with`. + /// Returns the dot product of this vector and . /// /// The other vector to use. /// The dot product of the two vectors. @@ -259,7 +272,7 @@ namespace Godot } /// - /// Returns the inverse of this vector. This is the same as `new Vector2(1 / v.x, 1 / v.y)`. + /// Returns the inverse of this vector. This is the same as new Vector2(1 / v.x, 1 / v.y). /// /// The inverse of this vector. public Vector2 Inverse() @@ -268,9 +281,9 @@ namespace Godot } /// - /// Returns true if the vector is normalized, and false otherwise. + /// Returns if the vector is normalized, and otherwise. /// - /// A bool indicating whether or not the vector is normalized. + /// A indicating whether or not the vector is normalized. public bool IsNormalized() { return Mathf.Abs(LengthSquared() - 1.0f) < Mathf.Epsilon; @@ -279,6 +292,7 @@ namespace Godot /// /// Returns the length (magnitude) of this vector. /// + /// /// The length of this vector. public real_t Length() { @@ -298,7 +312,7 @@ namespace Godot /// /// Returns the result of the linear interpolation between - /// this vector and `to` by amount `weight`. + /// this vector and by amount . /// /// The destination vector for interpolation. /// A value on the range of 0.0 to 1.0, representing the amount of interpolation. @@ -314,10 +328,12 @@ namespace Godot /// /// Returns the result of the linear interpolation between - /// this vector and `to` by the vector amount `weight`. + /// this vector and by the vector amount . /// /// The destination vector for interpolation. - /// A vector with components on the range of 0.0 to 1.0, representing the amount of interpolation. + /// + /// A vector with components on the range of 0.0 to 1.0, representing the amount of interpolation. + /// /// The resulting vector of the interpolation. public Vector2 LinearInterpolate(Vector2 to, Vector2 weight) { @@ -349,7 +365,7 @@ namespace Godot } /// - /// Moves this vector toward `to` by the fixed `delta` amount. + /// Moves this vector toward by the fixed amount. /// /// The vector to move towards. /// The amount to move towards by. @@ -363,7 +379,7 @@ namespace Godot } /// - /// Returns the vector scaled to unit length. Equivalent to `v / v.Length()`. + /// Returns the vector scaled to unit length. Equivalent to v / v.Length(). /// /// A normalized version of the vector. public Vector2 Normalized() @@ -384,10 +400,13 @@ namespace Godot } /// - /// Returns a vector composed of the of this vector's components and `mod`. + /// Returns a vector composed of the of this vector's components + /// and . /// /// A value representing the divisor of the operation. - /// A vector with each component by `mod`. + /// + /// A vector with each component by . + /// public Vector2 PosMod(real_t mod) { Vector2 v; @@ -397,10 +416,13 @@ namespace Godot } /// - /// Returns a vector composed of the of this vector's components and `modv`'s components. + /// Returns a vector composed of the of this vector's components + /// and 's components. /// /// A vector representing the divisors of the operation. - /// A vector with each component by `modv`'s components. + /// + /// A vector with each component by 's components. + /// public Vector2 PosMod(Vector2 modv) { Vector2 v; @@ -410,7 +432,7 @@ namespace Godot } /// - /// Returns this vector projected onto another vector. + /// Returns this vector projected onto another vector . /// /// The vector to project onto. /// The projected vector. @@ -420,7 +442,7 @@ namespace Godot } /// - /// Returns this vector reflected from a plane defined by the given `normal`. + /// Returns this vector reflected from a plane defined by the given . /// /// The normal vector defining the plane to reflect from. Must be normalized. /// The reflected vector. @@ -436,7 +458,7 @@ namespace Godot } /// - /// Rotates this vector by `phi` radians. + /// Rotates this vector by radians. /// /// The angle to rotate by, in radians. /// The rotated vector. @@ -474,7 +496,7 @@ namespace Godot /// on the signs of this vector's components, or zero if the component is zero, /// by calling on each component. /// - /// A vector with all components as either `1`, `-1`, or `0`. + /// A vector with all components as either 1, -1, or 0. public Vector2 Sign() { Vector2 v; @@ -485,7 +507,7 @@ namespace Godot /// /// Returns the result of the spherical linear interpolation between - /// this vector and `to` by amount `weight`. + /// this vector and by amount . /// /// Note: Both vectors must be normalized. /// @@ -501,14 +523,14 @@ namespace Godot } if (!to.IsNormalized()) { - throw new InvalidOperationException("Vector2.Slerp: `to` is not normalized."); + throw new InvalidOperationException($"Vector2.Slerp: `{nameof(to)}` is not normalized."); } #endif return Rotated(AngleTo(to) * weight); } /// - /// Returns this vector slid along a plane defined by the given normal. + /// Returns this vector slid along a plane defined by the given . /// /// The normal vector defining the plane to slide on. /// The slid vector. @@ -518,7 +540,7 @@ namespace Godot } /// - /// Returns this vector with each component snapped to the nearest multiple of `step`. + /// Returns this vector with each component snapped to the nearest multiple of . /// This can also be used to round to an arbitrary number of decimals. /// /// A vector value representing the step size to snap to. @@ -551,45 +573,46 @@ namespace Godot private static readonly Vector2 _left = new Vector2(-1, 0); /// - /// Zero vector, a vector with all components set to `0`. + /// Zero vector, a vector with all components set to 0. /// - /// Equivalent to `new Vector2(0, 0)` + /// Equivalent to new Vector2(0, 0). public static Vector2 Zero { get { return _zero; } } /// /// Deprecated, please use a negative sign with instead. /// - /// Equivalent to `new Vector2(-1, -1)` + /// Equivalent to new Vector2(-1, -1). + [Obsolete("Use a negative sign with Vector2.One instead.")] public static Vector2 NegOne { get { return _negOne; } } /// - /// One vector, a vector with all components set to `1`. + /// One vector, a vector with all components set to 1. /// - /// Equivalent to `new Vector2(1, 1)` + /// Equivalent to new Vector2(1, 1). public static Vector2 One { get { return _one; } } /// - /// Infinity vector, a vector with all components set to `Mathf.Inf`. + /// Infinity vector, a vector with all components set to . /// - /// Equivalent to `new Vector2(Mathf.Inf, Mathf.Inf)` + /// Equivalent to new Vector2(Mathf.Inf, Mathf.Inf). public static Vector2 Inf { get { return _inf; } } /// /// Up unit vector. Y is down in 2D, so this vector points -Y. /// - /// Equivalent to `new Vector2(0, -1)` + /// Equivalent to new Vector2(0, -1). public static Vector2 Up { get { return _up; } } /// /// Down unit vector. Y is down in 2D, so this vector points +Y. /// - /// Equivalent to `new Vector2(0, 1)` + /// Equivalent to new Vector2(0, 1). public static Vector2 Down { get { return _down; } } /// /// Right unit vector. Represents the direction of right. /// - /// Equivalent to `new Vector2(1, 0)` + /// Equivalent to new Vector2(1, 0). public static Vector2 Right { get { return _right; } } /// /// Left unit vector. Represents the direction of left. /// - /// Equivalent to `new Vector2(-1, 0)` + /// Equivalent to new Vector2(-1, 0). public static Vector2 Left { get { return _left; } } /// @@ -729,6 +752,11 @@ namespace Godot return left.x >= right.x; } + /// + /// Returns if this vector and are equal. + /// + /// The other object to compare. + /// Whether or not the vector and the other object are equal. public override bool Equals(object obj) { if (obj is Vector2) @@ -738,14 +766,19 @@ namespace Godot return false; } + /// + /// Returns if this vector and are equal. + /// + /// The other vector to compare. + /// Whether or not the vectors are equal. public bool Equals(Vector2 other) { return x == other.x && y == other.y; } /// - /// Returns true if this vector and `other` are approximately equal, by running - /// on each component. + /// Returns if this vector and are approximately equal, + /// by running on each component. /// /// The other vector to compare. /// Whether or not the vectors are approximately equal. @@ -754,11 +787,19 @@ namespace Godot return Mathf.IsEqualApprox(x, other.x) && Mathf.IsEqualApprox(y, other.y); } + /// + /// Serves as the hash function for . + /// + /// A hash code for this vector. public override int GetHashCode() { return y.GetHashCode() ^ x.GetHashCode(); } + /// + /// Converts this to a string. + /// + /// A string representation of this vector. public override string ToString() { return String.Format("({0}, {1})", new object[] @@ -768,6 +809,10 @@ namespace Godot }); } + /// + /// Converts this to a string with the given . + /// + /// A string representation of this vector. public string ToString(string format) { return String.Format("({0}, {1})", new object[] diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Vector3.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Vector3.cs index 1d2b41a8b29..3a5dd3a7812 100644 --- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Vector3.cs +++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Vector3.cs @@ -21,28 +21,44 @@ namespace Godot /// public enum Axis { + /// + /// The vector's X axis. + /// X = 0, + /// + /// The vector's Y axis. + /// Y, + /// + /// The vector's Z axis. + /// Z } /// - /// The vector's X component. Also accessible by using the index position `[0]`. + /// The vector's X component. Also accessible by using the index position [0]. /// public real_t x; /// - /// The vector's Y component. Also accessible by using the index position `[1]`. + /// The vector's Y component. Also accessible by using the index position [1]. /// public real_t y; /// - /// The vector's Z component. Also accessible by using the index position `[2]`. + /// The vector's Z component. Also accessible by using the index position [2]. /// public real_t z; /// /// Access vector components using their index. /// - /// `[0]` is equivalent to `.x`, `[1]` is equivalent to `.y`, `[2]` is equivalent to `.z`. + /// + /// Thrown when the given the is not 0, 1 or 2. + /// + /// + /// [0] is equivalent to , + /// [1] is equivalent to , + /// [2] is equivalent to . + /// public real_t this[int index] { get @@ -134,7 +150,7 @@ namespace Godot } /// - /// Returns the cross product of this vector and `b`. + /// Returns the cross product of this vector and . /// /// The other vector. /// The cross product vector. @@ -149,12 +165,12 @@ namespace Godot } /// - /// Performs a cubic interpolation between vectors `preA`, this vector, - /// `b`, and `postB`, by the given amount `t`. + /// Performs a cubic interpolation between vectors , this vector, + /// , and , by the given amount . /// /// The destination vector. /// A vector before this vector. - /// A vector after `b`. + /// A vector after . /// A value on the range of 0.0 to 1.0, representing the amount of interpolation. /// The interpolated vector. public Vector3 CubicInterpolate(Vector3 b, Vector3 preA, Vector3 postB, real_t weight) @@ -176,17 +192,17 @@ namespace Godot } /// - /// Returns the normalized vector pointing from this vector to `b`. + /// Returns the normalized vector pointing from this vector to . /// /// The other vector to point towards. - /// The direction from this vector to `b`. + /// The direction from this vector to . public Vector3 DirectionTo(Vector3 b) { return new Vector3(b.x - x, b.y - y, b.z - z).Normalized(); } /// - /// Returns the squared distance between this vector and `b`. + /// Returns the squared distance between this vector and . /// This method runs faster than , so prefer it if /// you need to compare vectors or need the squared distance for some formula. /// @@ -198,8 +214,9 @@ namespace Godot } /// - /// Returns the distance between this vector and `b`. + /// Returns the distance between this vector and . /// + /// /// The other vector to use. /// The distance between the two vectors. public real_t DistanceTo(Vector3 b) @@ -208,7 +225,7 @@ namespace Godot } /// - /// Returns the dot product of this vector and `b`. + /// Returns the dot product of this vector and . /// /// The other vector to use. /// The dot product of the two vectors. @@ -227,7 +244,7 @@ namespace Godot } /// - /// Returns the inverse of this vector. This is the same as `new Vector3(1 / v.x, 1 / v.y, 1 / v.z)`. + /// Returns the inverse of this vector. This is the same as new Vector3(1 / v.x, 1 / v.y, 1 / v.z). /// /// The inverse of this vector. public Vector3 Inverse() @@ -236,9 +253,9 @@ namespace Godot } /// - /// Returns true if the vector is normalized, and false otherwise. + /// Returns if the vector is normalized, and otherwise. /// - /// A bool indicating whether or not the vector is normalized. + /// A indicating whether or not the vector is normalized. public bool IsNormalized() { return Mathf.Abs(LengthSquared() - 1.0f) < Mathf.Epsilon; @@ -247,6 +264,7 @@ namespace Godot /// /// Returns the length (magnitude) of this vector. /// + /// /// The length of this vector. public real_t Length() { @@ -274,7 +292,7 @@ namespace Godot /// /// Returns the result of the linear interpolation between - /// this vector and `to` by amount `weight`. + /// this vector and by amount . /// /// The destination vector for interpolation. /// A value on the range of 0.0 to 1.0, representing the amount of interpolation. @@ -291,7 +309,7 @@ namespace Godot /// /// Returns the result of the linear interpolation between - /// this vector and `to` by the vector amount `weight`. + /// this vector and by the vector amount . /// /// The destination vector for interpolation. /// A vector with components on the range of 0.0 to 1.0, representing the amount of interpolation. @@ -327,7 +345,7 @@ namespace Godot } /// - /// Moves this vector toward `to` by the fixed `delta` amount. + /// Moves this vector toward by the fixed amount. /// /// The vector to move towards. /// The amount to move towards by. @@ -341,7 +359,7 @@ namespace Godot } /// - /// Returns the vector scaled to unit length. Equivalent to `v / v.Length()`. + /// Returns the vector scaled to unit length. Equivalent to v / v.Length(). /// /// A normalized version of the vector. public Vector3 Normalized() @@ -352,7 +370,7 @@ namespace Godot } /// - /// Returns the outer product with `b`. + /// Returns the outer product with . /// /// The other vector. /// A representing the outer product matrix. @@ -366,10 +384,13 @@ namespace Godot } /// - /// Returns a vector composed of the of this vector's components and `mod`. + /// Returns a vector composed of the of this vector's components + /// and . /// /// A value representing the divisor of the operation. - /// A vector with each component by `mod`. + /// + /// A vector with each component by . + /// public Vector3 PosMod(real_t mod) { Vector3 v; @@ -380,10 +401,13 @@ namespace Godot } /// - /// Returns a vector composed of the of this vector's components and `modv`'s components. + /// Returns a vector composed of the of this vector's components + /// and 's components. /// /// A vector representing the divisors of the operation. - /// A vector with each component by `modv`'s components. + /// + /// A vector with each component by 's components. + /// public Vector3 PosMod(Vector3 modv) { Vector3 v; @@ -394,7 +418,7 @@ namespace Godot } /// - /// Returns this vector projected onto another vector `b`. + /// Returns this vector projected onto another vector . /// /// The vector to project onto. /// The projected vector. @@ -404,7 +428,7 @@ namespace Godot } /// - /// Returns this vector reflected from a plane defined by the given `normal`. + /// Returns this vector reflected from a plane defined by the given . /// /// The normal vector defining the plane to reflect from. Must be normalized. /// The reflected vector. @@ -420,8 +444,8 @@ namespace Godot } /// - /// Rotates this vector around a given `axis` vector by `phi` radians. - /// The `axis` vector must be a normalized vector. + /// Rotates this vector around a given vector by radians. + /// The vector must be a normalized vector. /// /// The vector to rotate around. Must be normalized. /// The angle to rotate by, in radians. @@ -467,7 +491,7 @@ namespace Godot /// on the signs of this vector's components, or zero if the component is zero, /// by calling on each component. /// - /// A vector with all components as either `1`, `-1`, or `0`. + /// A vector with all components as either 1, -1, or 0. public Vector3 Sign() { Vector3 v; @@ -481,7 +505,7 @@ namespace Godot /// Returns the signed angle to the given vector, in radians. /// The sign of the angle is positive in a counter-clockwise /// direction and negative in a clockwise direction when viewed - /// from the side specified by the `axis`. + /// from the side specified by the . /// /// The other vector to compare this vector to. /// The reference axis to use for the angle sign. @@ -496,7 +520,7 @@ namespace Godot /// /// Returns the result of the spherical linear interpolation between - /// this vector and `to` by amount `weight`. + /// this vector and by amount . /// /// Note: Both vectors must be normalized. /// @@ -512,7 +536,7 @@ namespace Godot } if (!to.IsNormalized()) { - throw new InvalidOperationException("Vector3.Slerp: `to` is not normalized."); + throw new InvalidOperationException($"Vector3.Slerp: `{nameof(to)}` is not normalized."); } #endif real_t theta = AngleTo(to); @@ -520,7 +544,7 @@ namespace Godot } /// - /// Returns this vector slid along a plane defined by the given normal. + /// Returns this vector slid along a plane defined by the given . /// /// The normal vector defining the plane to slide on. /// The slid vector. @@ -530,7 +554,7 @@ namespace Godot } /// - /// Returns this vector with each component snapped to the nearest multiple of `step`. + /// Returns this vector with each component snapped to the nearest multiple of . /// This can also be used to round to an arbitrary number of decimals. /// /// A vector value representing the step size to snap to. @@ -548,10 +572,10 @@ namespace Godot /// /// Returns a diagonal matrix with the vector as main diagonal. /// - /// This is equivalent to a Basis with no rotation or shearing and + /// This is equivalent to a with no rotation or shearing and /// this vector's components set as the scale. /// - /// A Basis with the vector as its main diagonal. + /// A with the vector as its main diagonal. public Basis ToDiagonalMatrix() { return new Basis( @@ -575,59 +599,60 @@ namespace Godot private static readonly Vector3 _back = new Vector3(0, 0, 1); /// - /// Zero vector, a vector with all components set to `0`. + /// Zero vector, a vector with all components set to 0. /// - /// Equivalent to `new Vector3(0, 0, 0)` + /// Equivalent to new Vector3(0, 0, 0). public static Vector3 Zero { get { return _zero; } } /// - /// One vector, a vector with all components set to `1`. + /// One vector, a vector with all components set to 1. /// - /// Equivalent to `new Vector3(1, 1, 1)` + /// Equivalent to new Vector3(1, 1, 1). public static Vector3 One { get { return _one; } } /// /// Deprecated, please use a negative sign with instead. /// - /// Equivalent to `new Vector3(-1, -1, -1)` + /// Equivalent to new Vector3(-1, -1, -1). + [Obsolete("Use a negative sign with Vector3.One instead.")] public static Vector3 NegOne { get { return _negOne; } } /// - /// Infinity vector, a vector with all components set to `Mathf.Inf`. + /// Infinity vector, a vector with all components set to . /// - /// Equivalent to `new Vector3(Mathf.Inf, Mathf.Inf, Mathf.Inf)` + /// Equivalent to new Vector3(Mathf.Inf, Mathf.Inf, Mathf.Inf). public static Vector3 Inf { get { return _inf; } } /// /// Up unit vector. /// - /// Equivalent to `new Vector3(0, 1, 0)` + /// Equivalent to new Vector3(0, 1, 0). public static Vector3 Up { get { return _up; } } /// /// Down unit vector. /// - /// Equivalent to `new Vector3(0, -1, 0)` + /// Equivalent to new Vector3(0, -1, 0). public static Vector3 Down { get { return _down; } } /// /// Right unit vector. Represents the local direction of right, /// and the global direction of east. /// - /// Equivalent to `new Vector3(1, 0, 0)` + /// Equivalent to new Vector3(1, 0, 0). public static Vector3 Right { get { return _right; } } /// /// Left unit vector. Represents the local direction of left, /// and the global direction of west. /// - /// Equivalent to `new Vector3(-1, 0, 0)` + /// Equivalent to new Vector3(-1, 0, 0). public static Vector3 Left { get { return _left; } } /// /// Forward unit vector. Represents the local direction of forward, /// and the global direction of north. /// - /// Equivalent to `new Vector3(0, 0, -1)` + /// Equivalent to new Vector3(0, 0, -1). public static Vector3 Forward { get { return _forward; } } /// /// Back unit vector. Represents the local direction of back, /// and the global direction of south. /// - /// Equivalent to `new Vector3(0, 0, 1)` + /// Equivalent to new Vector3(0, 0, 1). public static Vector3 Back { get { return _back; } } /// @@ -796,6 +821,11 @@ namespace Godot return left.x > right.x; } + /// + /// Returns if this vector and are equal. + /// + /// The other object to compare. + /// Whether or not the vector and the other object are equal. public override bool Equals(object obj) { if (obj is Vector3) @@ -806,14 +836,19 @@ namespace Godot return false; } + /// + /// Returns if this vector and are equal + /// + /// The other vector to compare. + /// Whether or not the vectors are equal. public bool Equals(Vector3 other) { return x == other.x && y == other.y && z == other.z; } /// - /// Returns true if this vector and `other` are approximately equal, by running - /// on each component. + /// Returns if this vector and are approximately equal, + /// by running on each component. /// /// The other vector to compare. /// Whether or not the vectors are approximately equal. @@ -822,11 +857,19 @@ namespace Godot return Mathf.IsEqualApprox(x, other.x) && Mathf.IsEqualApprox(y, other.y) && Mathf.IsEqualApprox(z, other.z); } + /// + /// Serves as the hash function for . + /// + /// A hash code for this vector. public override int GetHashCode() { return y.GetHashCode() ^ x.GetHashCode() ^ z.GetHashCode(); } + /// + /// Converts this to a string. + /// + /// A string representation of this vector. public override string ToString() { return String.Format("({0}, {1}, {2})", new object[] @@ -837,6 +880,10 @@ namespace Godot }); } + /// + /// Converts this to a string with the given . + /// + /// A string representation of this vector. public string ToString(string format) { return String.Format("({0}, {1}, {2})", new object[]