From 9c7f03aefc7d6918002641447cb979502ebea686 Mon Sep 17 00:00:00 2001
From: smix8 <52464204+smix8@users.noreply.github.com>
Date: Fri, 3 Jun 2022 21:44:46 +0200
Subject: Document the correct use of NavigationAgent path functions

Document the correct use of NavigationAgent path functions.
---
 doc/classes/NavigationAgent2D.xml | 5 +++--
 doc/classes/NavigationAgent3D.xml | 5 +++--
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/doc/classes/NavigationAgent2D.xml b/doc/classes/NavigationAgent2D.xml
index 942579f564..945947ad9f 100644
--- a/doc/classes/NavigationAgent2D.xml
+++ b/doc/classes/NavigationAgent2D.xml
@@ -5,6 +5,7 @@
 	</brief_description>
 	<description>
 		2D Agent that is used in navigation to reach a location while avoiding static and dynamic obstacles. The dynamic obstacles are avoided using RVO collision avoidance. The agent needs navigation data to work correctly. [NavigationAgent2D] is physics safe.
+		[b]Note:[/b] After [method set_target_location] is used it is required to use the [method get_next_location] function once every physics frame to update the internal path logic of the NavigationAgent. The returned vector position from this function should be used as the next movement position for the agent's parent Node.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -24,7 +25,7 @@
 		<method name="get_nav_path" qualifiers="const">
 			<return type="PackedVector2Array" />
 			<description>
-				Returns the path from start to finish in global coordinates.
+				Returns this agent's current path from start to finish in global coordinates. The path only updates when the target location is changed or the agent requires a repath. The path array is not intended to be used in direct path movement as the agent has its own internal path logic that would get corrupted by changing the path array manually. Use the intended [method get_next_location] once every physics frame to receive the next path point for the agents movement as this function also updates the internal path logic.
 			</description>
 		</method>
 		<method name="get_nav_path_index" qualifiers="const">
@@ -36,7 +37,7 @@
 		<method name="get_next_location">
 			<return type="Vector2" />
 			<description>
-				Returns a [Vector2] in global coordinates, that can be moved to, making sure that there are no static objects in the way. If the agent does not have a navigation path, it will return the position of the agent's parent.
+				Returns the next location in global coordinates that can be moved to, making sure that there are no static objects in the way. If the agent does not have a navigation path, it will return the position of the agent's parent. The use of this function once every physics frame is required to update the internal path logic of the NavigationAgent.
 			</description>
 		</method>
 		<method name="get_rid" qualifiers="const">
diff --git a/doc/classes/NavigationAgent3D.xml b/doc/classes/NavigationAgent3D.xml
index db2210b6e3..7f7e058742 100644
--- a/doc/classes/NavigationAgent3D.xml
+++ b/doc/classes/NavigationAgent3D.xml
@@ -5,6 +5,7 @@
 	</brief_description>
 	<description>
 		3D Agent that is used in navigation to reach a location while avoiding static and dynamic obstacles. The dynamic obstacles are avoided using RVO collision avoidance. The agent needs navigation data to work correctly. [NavigationAgent3D] is physics safe.
+		[b]Note:[/b] After [method set_target_location] is used it is required to use the [method get_next_location] function once every physics frame to update the internal path logic of the NavigationAgent. The returned vector position from this function should be used as the next movement position for the agent's parent Node.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -24,7 +25,7 @@
 		<method name="get_nav_path" qualifiers="const">
 			<return type="PackedVector3Array" />
 			<description>
-				Returns the path from start to finish in global coordinates.
+				Returns this agent's current path from start to finish in global coordinates. The path only updates when the target location is changed or the agent requires a repath. The path array is not intended to be used in direct path movement as the agent has its own internal path logic that would get corrupted by changing the path array manually. Use the intended [method get_next_location] once every physics frame to receive the next path point for the agents movement as this function also updates the internal path logic.
 			</description>
 		</method>
 		<method name="get_nav_path_index" qualifiers="const">
@@ -36,7 +37,7 @@
 		<method name="get_next_location">
 			<return type="Vector3" />
 			<description>
-				Returns a [Vector3] in global coordinates, that can be moved to, making sure that there are no static objects in the way. If the agent does not have a navigation path, it will return the origin of the agent's parent.
+				Returns the next location in global coordinates that can be moved to, making sure that there are no static objects in the way. If the agent does not have a navigation path, it will return the position of the agent's parent. The use of this function once every physics frame is required to update the internal path logic of the NavigationAgent.
 			</description>
 		</method>
 		<method name="get_rid" qualifiers="const">
-- 
cgit v1.2.3