Update core documentation to match recent C# changes

Also a few minor API changes like adding AABB.abs()

Co-authored-by: Rémi Verschelde <rverschelde@gmail.com>

8 files changed, 48 insertions, 58 deletions

diff --git a/modules/gdnative/gdnative/aabb.cpp b/modules/gdnative/gdnative/aabb.cpp
index 7f22c7dfe3..d5970e8004 100644
--- a/modules/gdnative/gdnative/aabb.cpp
+++ b/modules/gdnative/gdnative/aabb.cpp
@@ -81,6 +81,13 @@ godot_string GDAPI godot_aabb_as_string(const godot_aabb *p_self) {
 	return ret;
 }
 
+godot_aabb GDAPI godot_aabb_abs(const godot_aabb *p_self) {
+	godot_aabb dest;
+	const AABB *self = (const AABB *)p_self;
+	*((AABB *)&dest) = self->abs();
+	return dest;
+}
+
 godot_real GDAPI godot_aabb_get_area(const godot_aabb *p_self) {
 	const AABB *self = (const AABB *)p_self;
 	return self->get_area();
diff --git a/modules/gdnative/gdnative/plane.cpp b/modules/gdnative/gdnative/plane.cpp
index 663937f906..d4ed8d00f4 100644
--- a/modules/gdnative/gdnative/plane.cpp
+++ b/modules/gdnative/gdnative/plane.cpp
@@ -79,13 +79,6 @@ godot_vector3 GDAPI godot_plane_center(const godot_plane *p_self) {
 	return dest;
 }
 
-godot_vector3 GDAPI godot_plane_get_any_point(const godot_plane *p_self) {
-	godot_vector3 dest;
-	const Plane *self = (const Plane *)p_self;
-	*((Vector3 *)&dest) = self->get_any_point();
-	return dest;
-}
-
 godot_bool GDAPI godot_plane_is_point_over(const godot_plane *p_self, const godot_vector3 *p_point) {
 	const Plane *self = (const Plane *)p_self;
 	const Vector3 *point = (const Vector3 *)p_point;
diff --git a/modules/gdnative/gdnative_api.json b/modules/gdnative/gdnative_api.json
index eb122089b6..9852928d22 100644
--- a/modules/gdnative/gdnative_api.json
+++ b/modules/gdnative/gdnative_api.json
@@ -54,6 +54,13 @@
         ]
       },
       {
+        "name": "godot_aabb_abs",
+        "return_type": "godot_aabb",
+        "arguments": [
+          ["const godot_aabb *", "p_self"]
+        ]
+      },
+      {
         "name": "godot_aabb_get_area",
         "return_type": "godot_real",
         "arguments": [
@@ -2981,13 +2988,6 @@
         ]
       },
       {
-        "name": "godot_plane_get_any_point",
-        "return_type": "godot_vector3",
-        "arguments": [
-          ["const godot_plane *", "p_self"]
-        ]
-      },
-      {
         "name": "godot_plane_is_point_over",
         "return_type": "godot_bool",
         "arguments": [
diff --git a/modules/gdnative/include/gdnative/aabb.h b/modules/gdnative/include/gdnative/aabb.h
index 9f41e9d4c6..c776297944 100644
--- a/modules/gdnative/include/gdnative/aabb.h
+++ b/modules/gdnative/include/gdnative/aabb.h
@@ -69,6 +69,8 @@ void GDAPI godot_aabb_set_size(const godot_aabb *p_self, const godot_vector3 *p_
 
 godot_string GDAPI godot_aabb_as_string(const godot_aabb *p_self);
 
+godot_aabb GDAPI godot_aabb_abs(const godot_aabb *p_self);
+
 godot_real GDAPI godot_aabb_get_area(const godot_aabb *p_self);
 
 godot_bool GDAPI godot_aabb_has_no_area(const godot_aabb *p_self);
diff --git a/modules/gdnative/include/gdnative/plane.h b/modules/gdnative/include/gdnative/plane.h
index b759a8cc1a..9843056489 100644
--- a/modules/gdnative/include/gdnative/plane.h
+++ b/modules/gdnative/include/gdnative/plane.h
@@ -68,8 +68,6 @@ godot_plane GDAPI godot_plane_normalized(const godot_plane *p_self);
 
 godot_vector3 GDAPI godot_plane_center(const godot_plane *p_self);
 
-godot_vector3 GDAPI godot_plane_get_any_point(const godot_plane *p_self);
-
 godot_bool GDAPI godot_plane_is_point_over(const godot_plane *p_self, const godot_vector3 *p_point);
 
 godot_real GDAPI godot_plane_distance_to(const godot_plane *p_self, const godot_vector3 *p_point);
diff --git a/modules/gdscript/doc_classes/@GDScript.xml b/modules/gdscript/doc_classes/@GDScript.xml
index f04cb4b4c3..36de66ea52 100644
--- a/modules/gdscript/doc_classes/@GDScript.xml
+++ b/modules/gdscript/doc_classes/@GDScript.xml
@@ -52,7 +52,7 @@
 			<argument index="0" name="s" type="float">
 			</argument>
 			<description>
-				Returns the absolute value of parameter [code]s[/code] (i.e. unsigned value, works for integer and float).
+				Returns the absolute value of parameter [code]s[/code] (i.e. positive value).
 				[codeblock]
 				# a is 1
 				a = abs(-1)
@@ -112,7 +112,7 @@
 			</argument>
 			<description>
 				Returns the arc tangent of [code]s[/code] in radians. Use it to get the angle from an angle's tangent in trigonometry: [code]atan(tan(angle)) == angle[/code].
-				The method cannot know in which quadrant the angle should fall. See [method atan2] if you always want an exact angle.
+				The method cannot know in which quadrant the angle should fall. See [method atan2] if you have both [code]y[code] and [code]x[/code].
 				[codeblock]
 				a = atan(0.5) # a is 0.463648
 				[/codeblock]
@@ -127,6 +127,7 @@
 			</argument>
 			<description>
 				Returns the arc tangent of [code]y/x[/code] in radians. Use to get the angle of tangent [code]y/x[/code]. 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.
 				[codeblock]
 				a = atan2(0, -1) # a is 3.141593
 				[/codeblock]
@@ -161,7 +162,7 @@
 			<argument index="0" name="s" type="float">
 			</argument>
 			<description>
-				Rounds [code]s[/code] upward, returning the smallest integral value that is not less than [code]s[/code].
+				Rounds [code]s[/code] upward (towards positive infinity), returning the smallest whole number that is not less than [code]s[/code].
 				[codeblock]
 				i = ceil(1.45)  # i is 2
 				i = ceil(1.001) # i is 2
@@ -283,7 +284,7 @@
 			<argument index="0" name="deg" type="float">
 			</argument>
 			<description>
-				Returns degrees converted to radians.
+				Converts an angle expressed in degrees to radians.
 				[codeblock]
 				# r is 3.141593
 				r = deg2rad(180)
@@ -307,7 +308,7 @@
 			<argument index="1" name="curve" type="float">
 			</argument>
 			<description>
-				Easing function, based on exponent. 0 is constant, 1 is linear, 0 to 1 is ease-in, 1+ is ease out. Negative values are in-out/out in.
+				Easing function, based on exponent. The curve values are: 0 is constant, 1 is linear, 0 to 1 is ease-in, 1+ is ease out. Negative values are in-out/out in.
 			</description>
 		</method>
 		<method name="exp">
@@ -330,7 +331,7 @@
 			<argument index="0" name="s" type="float">
 			</argument>
 			<description>
-				Rounds [code]s[/code] to the closest smaller integer and returns it.
+				Rounds [code]s[/code] downward (towards negative infinity), returning the largest whole number that is not more than [code]s[/code].
 				[codeblock]
 				# a is 2.0
 				a = floor(2.99)
@@ -530,7 +531,7 @@
 			<argument index="0" name="s" type="float">
 			</argument>
 			<description>
-				Returns whether [code]s[/code] is a NaN (Not-A-Number) value.
+				Returns whether [code]s[/code] is a NaN ("Not a Number" or invalid) value.
 			</description>
 		</method>
 		<method name="is_zero_approx">
@@ -540,6 +541,7 @@
 			</argument>
 			<description>
 				Returns [code]true[/code] if [code]s[/code] is zero or almost zero.
+				This method is faster than using [method is_equal_approx] with one value as zero.
 			</description>
 		</method>
 		<method name="len">
@@ -907,7 +909,7 @@
 			<argument index="0" name="rad" type="float">
 			</argument>
 			<description>
-				Converts from radians to degrees.
+				Converts an angle expressed in radians to degrees.
 				[codeblock]
 				rad2deg(0.523599) # Returns 30
 				[/codeblock]
@@ -1026,7 +1028,7 @@
 			<argument index="0" name="s" type="float">
 			</argument>
 			<description>
-				Returns the integral value that is nearest to [code]s[/code], with halfway cases rounded away from zero.
+				Rounds [code]s[/code] to the nearest whole number, with halfway cases rounded away from zero.
 				[codeblock]
 				round(2.6) # Returns 3
 				[/codeblock]
@@ -1108,10 +1110,11 @@
 			<argument index="0" name="s" type="float">
 			</argument>
 			<description>
-				Returns the square root of [code]s[/code].
+				Returns the square root of [code]s[/code], where [code]s[/code] is a non-negative number.
 				[codeblock]
 				sqrt(9) # Returns 3
 				[/codeblock]
+				If you need negative inputs, use [code]System.Numerics.Complex[/code] in C#.
 			</description>
 		</method>
 		<method name="step_decimals">
@@ -1312,27 +1315,19 @@
 				Wraps float [code]value[/code] between [code]min[/code] and [code]max[/code].
 				Usable for creating loop-alike behavior or infinite surfaces.
 				[codeblock]
-				# a is 0.5
-				a = wrapf(10.5, 0.0, 10.0)
-				[/codeblock]
-				[codeblock]
-				# a is 9.5
-				a = wrapf(-0.5, 0.0, 10.0)
-				[/codeblock]
-				[codeblock]
-				# Infinite loop between 0.0 and 0.99
-				f = wrapf(f + 0.1, 0.0, 1.0)
+				# Infinite loop between 5.0 and 9.9
+				value = wrapf(value + 0.1, 5.0, 10.0)
 				[/codeblock]
 				[codeblock]
 				# Infinite rotation (in radians)
 				angle = wrapf(angle + 0.1, 0.0, TAU)
 				[/codeblock]
-				[b]Note:[/b] If you just want to wrap between 0.0 and [code]n[/code] (where [code]n[/code] is a positive floating-point value), it is better for performance to use the [method fmod] method like [code]fmod(number, n)[/code].
-				[code]wrapf[/code] is more flexible than using the [method fmod] approach by giving the user a simple control over the minimum value. It also fully supports negative numbers, e.g.
 				[codeblock]
 				# Infinite rotation (in radians)
 				angle = wrapf(angle + 0.1, -PI, PI)
 				[/codeblock]
+				[b]Note:[/b] If [code]min[/code] is [code]0[/code], this is equivalent to [method fposmod], so prefer using that instead.
+				[code]wrapf[/code] is more flexible than using the [method fposmod] approach by giving the user control over the minimum value.
 			</description>
 		</method>
 		<method name="wrapi">
@@ -1348,23 +1343,15 @@
 				Wraps integer [code]value[/code] between [code]min[/code] and [code]max[/code].
 				Usable for creating loop-alike behavior or infinite surfaces.
 				[codeblock]
-				# a is 0
-				a = wrapi(10, 0, 10)
-				[/codeblock]
-				[codeblock]
-				# a is 9
-				a = wrapi(-1, 0, 10)
-				[/codeblock]
-				[codeblock]
-				# Infinite loop between 0 and 9
-				frame = wrapi(frame + 1, 0, 10)
+				# Infinite loop between 5 and 9
+				frame = wrapi(frame + 1, 5, 10)
 				[/codeblock]
-				[b]Note:[/b] If you just want to wrap between 0 and [code]n[/code] (where [code]n[/code] is a positive integer value), it is better for performance to use the modulo operator like [code]number % n[/code].
-				[code]wrapi[/code] is more flexible than using the modulo approach by giving the user a simple control over the minimum value. It also fully supports negative numbers, e.g.
 				[codeblock]
 				# result is -2
 				var result = wrapi(-6, -5, -1)
 				[/codeblock]
+				[b]Note:[/b] If [code]min[/code] is [code]0[/code], this is equivalent to [method posmod], so prefer using that instead.
+				[code]wrapi[/code] is more flexible than using the [method posmod] approach by giving the user control over the minimum value.
 			</description>
 		</method>
 		<method name="yield">
@@ -1406,17 +1393,16 @@
 	</methods>
 	<constants>
 		<constant name="PI" value="3.141593">
-			Constant that represents how many times the diameter of a circle fits around its perimeter.
+			Constant that represents how many times the diameter of a circle fits around its perimeter. This is equivalent to [code]TAU / 2[/code].
 		</constant>
 		<constant name="TAU" value="6.283185">
-			The circle constant, the circumference of the unit circle.
+			The circle constant, the circumference of the unit circle in radians.
 		</constant>
 		<constant name="INF" value="inf">
-			A positive infinity. (For negative infinity, use -INF).
+			Positive infinity. For negative infinity, use -INF.
 		</constant>
 		<constant name="NAN" value="nan">
-			Macro constant that expands to an expression of type float that represents a NaN.
-			The NaN values are used to identify undefined or non-representable values for floating-point elements, such as the square root of negative numbers or the result of 0/0.
+			"Not a Number", an invalid value. [code]NaN[/code] has special properties, including that it is not equal to itself. It is output by some invalid operations, such as dividing zero by zero.
 		</constant>
 	</constants>
 </class>
diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Color.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Color.cs
index 3173a21986..d851abc6d3 100644
--- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Color.cs
+++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Color.cs
@@ -486,7 +486,7 @@ namespace Godot
         }
 
         /// <summary>
-        /// Constructs a color from RGB values on the range of 0 to 1.
+        /// Constructs a color from RGBA values on the range of 0 to 1.
         /// </summary>
         /// <param name="r">The color's red component, typically on the range of 0 to 1.</param>
         /// <param name="g">The color's green component, typically on the range of 0 to 1.</param>
diff --git a/modules/mono/glue/GodotSharp/GodotSharp/Core/Plane.cs b/modules/mono/glue/GodotSharp/GodotSharp/Core/Plane.cs
index af0d474bae..2748454e48 100644
--- a/modules/mono/glue/GodotSharp/GodotSharp/Core/Plane.cs
+++ b/modules/mono/glue/GodotSharp/GodotSharp/Core/Plane.cs
@@ -20,8 +20,9 @@ namespace Godot
         private Vector3 _normal;
 
         /// <summary>
-        /// The normal of the plane (in the plane equation: a, b, and c).
-        /// The normal vector must be normalized.
+        /// 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 <see cref="D"> property.
         /// </summary>
         /// <value>Equivalent to `x`, `y`, and `z`.</value>
         public Vector3 Normal
@@ -81,6 +82,9 @@ namespace Godot
         /// <summary>
         /// The distance from the origin to the plane (in the direction of
         /// <see cref="Normal"/>). 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
+        /// by the <see cref="Normal"> property.
         /// </summary>
         /// <value>The plane's distance from the origin.</value>
         public real_t D { get; set; }