From 36c4451a7b39e0503b11218903624e1ea8ee46c8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C3=A9mi=20Verschelde?= <rverschelde@gmail.com>
Date: Thu, 11 Nov 2021 11:31:30 +0100
Subject: Rect2: Clarify docs for `has_point` excluding bottom and right
 borders

Improve tests, as well as documentation for `expand`.
---
 doc/classes/AABB.xml   | 17 ++++++++++++++++-
 doc/classes/Rect2.xml  | 20 ++++++++++++++++++--
 doc/classes/Rect2i.xml | 19 +++++++++++++++++--
 3 files changed, 51 insertions(+), 5 deletions(-)

(limited to 'doc/classes')

diff --git a/doc/classes/AABB.xml b/doc/classes/AABB.xml
index f353cd19b8..15d146fba1 100644
--- a/doc/classes/AABB.xml
+++ b/doc/classes/AABB.xml
@@ -54,7 +54,22 @@
 			<return type="AABB" />
 			<argument index="0" name="to_point" type="Vector3" />
 			<description>
-				Returns this [AABB] expanded to include a given point.
+				Returns a copy of this [AABB] expanded to include a given point.
+				[b]Example:[/b]
+				[codeblocks]
+				[gdscript]
+				# position (-3, 2, 0), size (1, 1, 1)
+				var box = AABB(Vector3(-3, 2, 0), Vector3(1, 1, 1))
+				# position (-3, -1, 0), size (3, 4, 2), so we fit both the original AABB and Vector3(0, -1, 2)
+				var box2 = box.expand(Vector3(0, -1, 2))
+				[/gdscript]
+				[csharp]
+				// position (-3, 2, 0), size (1, 1, 1)
+				var box = new AABB(new Vector3(-3, 2, 0), new Vector3(1, 1, 1));
+				// position (-3, -1, 0), size (3, 4, 2), so we fit both the original AABB and Vector3(0, -1, 2)
+				var box2 = box.Expand(new Vector3(0, -1, 2));
+				[/csharp]
+				[/codeblocks]
 			</description>
 		</method>
 		<method name="get_center" qualifiers="const">
diff --git a/doc/classes/Rect2.xml b/doc/classes/Rect2.xml
index 01bec10ed8..ad88551d9d 100644
--- a/doc/classes/Rect2.xml
+++ b/doc/classes/Rect2.xml
@@ -71,7 +71,22 @@
 			<return type="Rect2" />
 			<argument index="0" name="to" type="Vector2" />
 			<description>
-				Returns this [Rect2] expanded to include a given point.
+				Returns a copy of this [Rect2] expanded to include a given point.
+				[b]Example:[/b]
+				[codeblocks]
+				[gdscript]
+				# position (-3, 2), size (1, 1)
+				var rect = Rect2(Vector2(-3, 2), Vector2(1, 1))
+				# position (-3, -1), size (3, 4), so we fit both rect and Vector2(0, -1)
+				var rect2 = rect.expand(Vector2(0, -1))
+				[/gdscript]
+				[csharp]
+				# position (-3, 2), size (1, 1)
+				var rect = new Rect2(new Vector2(-3, 2), new Vector2(1, 1));
+				# position (-3, -1), size (3, 4), so we fit both rect and Vector2(0, -1)
+				var rect2 = rect.Expand(new Vector2(0, -1));
+				[/csharp]
+				[/codeblocks]
 			</description>
 		</method>
 		<method name="get_area" qualifiers="const">
@@ -121,7 +136,8 @@
 			<return type="bool" />
 			<argument index="0" name="point" type="Vector2" />
 			<description>
-				Returns [code]true[/code] if the [Rect2] contains a point.
+				Returns [code]true[/code] if the [Rect2] contains a point. By convention, the right and bottom edges of the [Rect2] are considered exclusive, so points on these edges are [b]not[/b] included.
+				[b]Note:[/b] This method is not reliable for [Rect2] with a [i]negative size[/i]. Use [method abs] to get a positive sized equivalent rectangle to check for contained points.
 			</description>
 		</method>
 		<method name="intersection" qualifiers="const">
diff --git a/doc/classes/Rect2i.xml b/doc/classes/Rect2i.xml
index fc27c64fa5..f5ea6a6c87 100644
--- a/doc/classes/Rect2i.xml
+++ b/doc/classes/Rect2i.xml
@@ -69,7 +69,21 @@
 			<return type="Rect2i" />
 			<argument index="0" name="to" type="Vector2i" />
 			<description>
-				Returns this [Rect2i] expanded to include a given point.
+				Returns a copy of this [Rect2i] expanded to include a given point.
+				[codeblocks]
+				[gdscript]
+				# position (-3, 2), size (1, 1)
+				var rect = Rect2i(Vector2i(-3, 2), Vector2i(1, 1))
+				# position (-3, -1), size (3, 4), so we fit both rect and Vector2i(0, -1)
+				var rect2 = rect.expand(Vector2i(0, -1))
+				[/gdscript]
+				[csharp]
+				# position (-3, 2), size (1, 1)
+				var rect = new Rect2i(new Vector2i(-3, 2), new Vector2i(1, 1));
+				# position (-3, -1), size (3, 4), so we fit both rect and Vector2i(0, -1)
+				var rect2 = rect.Expand(new Vector2i(0, -1));
+				[/csharp]
+				[/codeblocks]
 			</description>
 		</method>
 		<method name="get_area" qualifiers="const">
@@ -120,7 +134,8 @@
 			<return type="bool" />
 			<argument index="0" name="point" type="Vector2i" />
 			<description>
-				Returns [code]true[/code] if the [Rect2i] contains a point.
+				Returns [code]true[/code] if the [Rect2i] contains a point. By convention, the right and bottom edges of the [Rect2i] are considered exclusive, so points on these edges are [b]not[/b] included.
+				[b]Note:[/b] This method is not reliable for [Rect2i] with a [i]negative size[/i]. Use [method abs] to get a positive sized equivalent rectangle to check for contained points.
 			</description>
 		</method>
 		<method name="intersection" qualifiers="const">
-- 
cgit v1.2.3