From c6297f46fe236abbd6c6b06bb9b6bfaa239b49a5 Mon Sep 17 00:00:00 2001
From: Haoyu Qiu <timothyqiu32@gmail.com>
Date: Fri, 14 Apr 2023 14:39:35 +0800
Subject: Unify descriptions of vector methods

* is_equal_approx
* normalize
* length_squared
* posmod
* posmodv

(cherry picked from commit 6cd8e706fae5dacc908efd1a823e3447e01bfa56)
---
 core/variant/variant_call.cpp |  2 +-
 doc/classes/Vector2.xml       |  4 ++--
 doc/classes/Vector4.xml       | 11 ++++++-----
 doc/classes/Vector4i.xml      |  3 ++-
 4 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/core/variant/variant_call.cpp b/core/variant/variant_call.cpp
index 0c0c8f657a..c3617d4598 100644
--- a/core/variant/variant_call.cpp
+++ b/core/variant/variant_call.cpp
@@ -1906,7 +1906,7 @@ static void _register_variant_builtin_methods() {
 	bind_method(Vector4, distance_squared_to, sarray("to"), varray());
 	bind_method(Vector4, dot, sarray("with"), varray());
 	bind_method(Vector4, inverse, sarray(), varray());
-	bind_method(Vector4, is_equal_approx, sarray("with"), varray());
+	bind_method(Vector4, is_equal_approx, sarray("to"), varray());
 	bind_method(Vector4, is_zero_approx, sarray(), varray());
 	bind_method(Vector4, is_finite, sarray(), varray());
 
diff --git a/doc/classes/Vector2.xml b/doc/classes/Vector2.xml
index fe85ad7df6..9988b892db 100644
--- a/doc/classes/Vector2.xml
+++ b/doc/classes/Vector2.xml
@@ -214,7 +214,7 @@
 			<return type="bool" />
 			<param index="0" name="to" type="Vector2" />
 			<description>
-				Returns [code]true[/code] if this vector and [code]v[/code] are approximately equal, by running [method @GlobalScope.is_equal_approx] on each component.
+				Returns [code]true[/code] if this vector and [param to] are approximately equal, by running [method @GlobalScope.is_equal_approx] on each component.
 			</description>
 		</method>
 		<method name="is_finite" qualifiers="const">
@@ -288,7 +288,7 @@
 			<return type="Vector2" />
 			<description>
 				Returns the result of scaling the vector to unit length. Equivalent to [code]v / v.length()[/code]. See also [method is_normalized].
-				[b]Note:[/b] This function may return incorrect values if the initial vector length is near zero.
+				[b]Note:[/b] This function may return incorrect values if the input vector length is near zero.
 			</description>
 		</method>
 		<method name="orthogonal" qualifiers="const">
diff --git a/doc/classes/Vector4.xml b/doc/classes/Vector4.xml
index 7f71dc23ec..cb7a5b2b2d 100644
--- a/doc/classes/Vector4.xml
+++ b/doc/classes/Vector4.xml
@@ -131,9 +131,9 @@
 		</method>
 		<method name="is_equal_approx" qualifiers="const">
 			<return type="bool" />
-			<param index="0" name="with" type="Vector4" />
+			<param index="0" name="to" type="Vector4" />
 			<description>
-				Returns [code]true[/code] if this vector and [param with] are approximately equal, by running [method @GlobalScope.is_equal_approx] on each component.
+				Returns [code]true[/code] if this vector and [param to] are approximately equal, by running [method @GlobalScope.is_equal_approx] on each component.
 			</description>
 		</method>
 		<method name="is_finite" qualifiers="const">
@@ -164,7 +164,8 @@
 		<method name="length_squared" qualifiers="const">
 			<return type="float" />
 			<description>
-				Returns the squared length (squared magnitude) of this vector. This method runs faster than [method length].
+				Returns the squared length (squared magnitude) of this vector.
+				This method runs faster than [method length], so prefer it if you need to compare vectors or need the squared distance for some formula.
 			</description>
 		</method>
 		<method name="lerp" qualifiers="const">
@@ -198,14 +199,14 @@
 			<return type="Vector4" />
 			<param index="0" name="mod" type="float" />
 			<description>
-				Returns a new vector composed of the [method @GlobalScope.fposmod] of this vector's components and [param mod].
+				Returns a vector composed of the [method @GlobalScope.fposmod] of this vector's components and [param mod].
 			</description>
 		</method>
 		<method name="posmodv" qualifiers="const">
 			<return type="Vector4" />
 			<param index="0" name="modv" type="Vector4" />
 			<description>
-				Returns a new vector composed of the [method @GlobalScope.fposmod] of this vector's components and [param modv]'s components.
+				Returns a vector composed of the [method @GlobalScope.fposmod] of this vector's components and [param modv]'s components.
 			</description>
 		</method>
 		<method name="round" qualifiers="const">
diff --git a/doc/classes/Vector4i.xml b/doc/classes/Vector4i.xml
index 0885525d7c..92e01c7ce4 100644
--- a/doc/classes/Vector4i.xml
+++ b/doc/classes/Vector4i.xml
@@ -65,7 +65,8 @@
 		<method name="length_squared" qualifiers="const">
 			<return type="int" />
 			<description>
-				Returns the squared length (squared magnitude) of this vector. This method runs faster than [method length].
+				Returns the squared length (squared magnitude) of this vector.
+				This method runs faster than [method length], so prefer it if you need to compare vectors or need the squared distance for some formula.
 			</description>
 		</method>
 		<method name="max_axis_index" qualifiers="const">
-- 
cgit v1.2.3