From 1421a4744a65cd533504e1e0b9ac84c4f586c87f Mon Sep 17 00:00:00 2001
From: Hugo Locurcio <hugo.locurcio@hugo.pro>
Date: Tue, 8 Nov 2022 01:06:11 +0100
Subject: [PATCH] Clarify the difference between Vector2/3's `reflect()` and
 `bounce()`

---
 doc/classes/Vector2.xml | 4 +++-
 doc/classes/Vector3.xml | 6 ++++--
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/doc/classes/Vector2.xml b/doc/classes/Vector2.xml
index 5590f823365c..5b4d9096d843 100644
--- a/doc/classes/Vector2.xml
+++ b/doc/classes/Vector2.xml
@@ -99,7 +99,8 @@
 			<return type="Vector2" />
 			<param index="0" name="n" type="Vector2" />
 			<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 [i]physical[/i] reflection, as opposed to [method reflect] which performs [i]mathematical[/i] reflection. Double-check which method you actually need to use, as other engines may use these terms differently.
 			</description>
 		</method>
 		<method name="ceil" qualifiers="const">
@@ -311,6 +312,7 @@
 			<param index="0" name="n" type="Vector2" />
 			<description>
 				Returns the vector reflected (i.e. mirrored, or symmetric) over a line defined by the given direction vector [param n].
+				[b]Note:[/b] [method reflect] performs [i]mathematical[/i] reflection, as opposed to [method bounce] which performs [i]physical[/i] reflection. Double-check which method you actually need to use, as other engines may use these terms differently.
 			</description>
 		</method>
 		<method name="rotated" qualifiers="const">
diff --git a/doc/classes/Vector3.xml b/doc/classes/Vector3.xml
index 1a2cdfe10eea..8379c7977a10 100644
--- a/doc/classes/Vector3.xml
+++ b/doc/classes/Vector3.xml
@@ -75,7 +75,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 [i]physical[/i] reflection, as opposed to [method reflect] which performs [i]mathematical[/i] reflection.
 			</description>
 		</method>
 		<method name="ceil" qualifiers="const">
@@ -294,7 +295,8 @@
 			<return type="Vector3" />
 			<param index="0" name="n" type="Vector3" />
 			<description>
-				Returns this vector reflected from a plane defined by the given normal.
+				Returns the vector reflected (i.e. mirrored, or symmetric) over a plane defined by the given direction vector [param n].
+				[b]Note:[/b] [method reflect] performs [i]mathematical[/i] reflection, as opposed to [method bounce] which performs [i]physical[/i] reflection. Double-check which method you actually need to use, as other engines may use these terms differently.
 			</description>
 		</method>
 		<method name="rotated" qualifiers="const">