Merge pull request #89404 from clayjohn/DOCS-bounce-reflect

Clarify bounce and reflect docs and update param names

3 files changed, 12 insertions, 8 deletions

diff --git a/core/variant/variant_call.cpp b/core/variant/variant_call.cpp
index ba7c44e405..d0d940c47d 100644
--- a/core/variant/variant_call.cpp
+++ b/core/variant/variant_call.cpp
@@ -1799,7 +1799,7 @@ static void _register_variant_builtin_methods() {
 	bind_method(Vector2, dot, sarray("with"), varray());
 	bind_method(Vector2, slide, sarray("n"), varray());
 	bind_method(Vector2, bounce, sarray("n"), varray());
-	bind_method(Vector2, reflect, sarray("n"), varray());
+	bind_method(Vector2, reflect, sarray("line"), varray());
 	bind_method(Vector2, cross, sarray("with"), varray());
 	bind_method(Vector2, abs, sarray(), varray());
 	bind_method(Vector2, sign, sarray(), varray());
@@ -1896,7 +1896,7 @@ static void _register_variant_builtin_methods() {
 	bind_method(Vector3, project, sarray("b"), varray());
 	bind_method(Vector3, slide, sarray("n"), varray());
 	bind_method(Vector3, bounce, sarray("n"), varray());
-	bind_method(Vector3, reflect, sarray("n"), varray());
+	bind_method(Vector3, reflect, sarray("direction"), varray());
 	bind_method(Vector3, sign, sarray(), varray());
 	bind_method(Vector3, octahedron_encode, sarray(), varray());
 	bind_static_method(Vector3, octahedron_decode, sarray("uv"), varray());
diff --git a/doc/classes/Vector2.xml b/doc/classes/Vector2.xml
index 0b39743a72..7b166a4fb0 100644
--- a/doc/classes/Vector2.xml
+++ b/doc/classes/Vector2.xml
@@ -110,7 +110,8 @@
 			<return type="Vector2" />
 			<param index="0" name="n" type="Vector2" />
 			<description>
-				Returns a new vector "bounced off" from a plane defined by the given normal.
+				Returns the vector "bounced off" from a line defined by the given normal [param n] perpendicular to the line.
+				[b]Note:[/b] [method bounce] performs the operation that most engines and frameworks call [code skip-lint]reflect()[/code].
 			</description>
 		</method>
 		<method name="ceil" qualifiers="const">
@@ -321,9 +322,10 @@
 		</method>
 		<method name="reflect" qualifiers="const">
 			<return type="Vector2" />
-			<param index="0" name="n" type="Vector2" />
+			<param index="0" name="line" type="Vector2" />
 			<description>
-				Returns the result of reflecting the vector from a line defined by the given direction vector [param n].
+				Returns the result of reflecting the vector from a line defined by the given direction vector [param line].
+				[b]Note:[/b] [method reflect] differs from what other engines and frameworks call [code skip-lint]reflect()[/code]. In other engines, [code skip-lint]reflect()[/code] takes a normal direction which is a direction perpendicular to the line. In Godot, you specify the direction of the line directly. See also [method bounce] which does what most engines call [code skip-lint]reflect()[/code].
 			</description>
 		</method>
 		<method name="rotated" qualifiers="const">
diff --git a/doc/classes/Vector3.xml b/doc/classes/Vector3.xml
index af1383fe22..031d91af78 100644
--- a/doc/classes/Vector3.xml
+++ b/doc/classes/Vector3.xml
@@ -86,7 +86,8 @@
 			<return type="Vector3" />
 			<param index="0" name="n" type="Vector3" />
 			<description>
-				Returns the vector "bounced off" from a plane defined by the given normal.
+				Returns the vector "bounced off" from a plane defined by the given normal [param n].
+				[b]Note:[/b] [method bounce] performs the operation that most engines and frameworks call [code skip-lint]reflect()[/code].
 			</description>
 		</method>
 		<method name="ceil" qualifiers="const">
@@ -306,9 +307,10 @@
 		</method>
 		<method name="reflect" qualifiers="const">
 			<return type="Vector3" />
-			<param index="0" name="n" type="Vector3" />
+			<param index="0" name="direction" type="Vector3" />
 			<description>
-				Returns the result of reflecting the vector from a plane defined by the given normal [param n].
+				Returns the result of reflecting the vector from a plane defined by the given direction vector [param direction].
+				[b]Note:[/b] [method reflect] differs from what other engines and frameworks call [code skip-lint]reflect()[/code]. In other engines, [code skip-lint]reflect()[/code] takes a normal direction which is a direction perpendicular to the plane. In Godot, you specify a direction parallel to the plane. See also [method bounce] which does what most engines call [code skip-lint]reflect()[/code].
 			</description>
 		</method>
 		<method name="rotated" qualifiers="const">