From f88e1087797f58ac6f92938e44b886f06ea69392 Mon Sep 17 00:00:00 2001
From: Blueberry Gecko <162060915+BlueberryGecko@users.noreply.github.com>
Date: Wed, 29 Oct 2025 02:05:27 +0100
Subject: [PATCH] Improve documentation for Vector2's angle-related methods

---
 doc/classes/Vector2.xml | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/doc/classes/Vector2.xml b/doc/classes/Vector2.xml
index d9b04527e4e..1f9c8f524c1 100644
--- a/doc/classes/Vector2.xml
+++ b/doc/classes/Vector2.xml
@@ -59,15 +59,15 @@
 			<description>
 				Returns this vector's angle with respect to the positive X axis, or [code](1, 0)[/code] vector, in radians.
 				For example, [code]Vector2.RIGHT.angle()[/code] will return zero, [code]Vector2.DOWN.angle()[/code] will return [code]PI / 2[/code] (a quarter turn, or 90 degrees), and [code]Vector2(1, -1).angle()[/code] will return [code]-PI / 4[/code] (a negative eighth turn, or -45 degrees).
+				This is equivalent to calling [method @GlobalScope.atan2] with [member y] and [member x].
 				[url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/vector2_angle.png]Illustration of the returned angle.[/url]
-				Equivalent to the result of [method @GlobalScope.atan2] when called with the vector's [member y] and [member x] as parameters: [code]atan2(y, x)[/code].
 			</description>
 		</method>
 		<method name="angle_to" qualifiers="const">
 			<return type="float" />
 			<param index="0" name="to" type="Vector2" />
 			<description>
-				Returns the signed angle to the given vector, in radians.
+				Returns the signed angle to the given vector, in radians. The result ranges from [code]-PI[/code] to [code]PI[/code] (inclusive).
 				[url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/vector2_angle_to.png]Illustration of the returned angle.[/url]
 			</description>
 		</method>
@@ -75,15 +75,15 @@
 			<return type="float" />
 			<param index="0" name="to" type="Vector2" />
 			<description>
-				Returns the angle between the line connecting the two points and the X axis, in radians.
-				[code]a.angle_to_point(b)[/code] is equivalent of doing [code](b - a).angle()[/code].
+				Returns the signed angle between the X axis and the line from this vector to point [param to], in radians. The result ranges from [code]-PI[/code] to [code]PI[/code] (inclusive).
+				[code]a.angle_to_point(b)[/code] is equivalent to [code](b - a).angle()[/code]. See also [method angle].
 				[url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/vector2_angle_to_point.png]Illustration of the returned angle.[/url]
 			</description>
 		</method>
 		<method name="aspect" qualifiers="const">
 			<return type="float" />
 			<description>
-				Returns the aspect ratio of this vector, the ratio of [member x] to [member y].
+				Returns this vector's aspect ratio, which is [member x] divided by [member y].
 			</description>
 		</method>
 		<method name="bezier_derivative" qualifiers="const">
@@ -173,7 +173,8 @@
 			<return type="Vector2" />
 			<param index="0" name="to" type="Vector2" />
 			<description>
-				Returns the normalized vector pointing from this vector to [param to]. This is equivalent to using [code](b - a).normalized()[/code].
+				Returns the normalized vector pointing from this vector to [param to].
+				[code]a.direction_to(b)[/code] is equivalent to [code](b - a).normalized()[/code]. See also [method normalized].
 			</description>
 		</method>
 		<method name="distance_squared_to" qualifiers="const">