Merge pull request #48367 from Calinou/doc-navigation-get-simple-path

Document `Navigation.get_simple_path()` often returning non-optimal results

doc/classes/Navigation.xml

@@ -5,6 +5,7 @@
 	</brief_description>
 	<description>
 		Provides navigation and pathfinding within a collection of [NavigationMesh]es. By default, these will be automatically collected from child [NavigationMeshInstance] nodes, but they can also be added on the fly with [method navmesh_add]. In addition to basic pathfinding, this class also assists with aligning navigation agents with the meshes they are navigating on.
+		[b]Note:[/b] The current navigation system has many known issues and will not always return optimal paths as expected. These issues will be fixed in Godot 4.0.
 	</description>
 	<tutorials>
 		<link title="3D Navmesh Demo">https://godotengine.org/asset-library/asset/124</link>
@@ -61,6 +62,7 @@
 			</argument>
 			<description>
 				Returns the path between two given points. Points are in local coordinate space. If [code]optimize[/code] is [code]true[/code] (the default), the agent properties associated with each [NavigationMesh] (radius, height, etc.) are considered in the path calculation, otherwise they are ignored.
+				[b]Note:[/b] This method has known issues and will often return non-optimal paths. These issues will be fixed in Godot 4.0.
 			</description>
 		</method>
 		<method name="navmesh_add">

doc/classes/Navigation2D.xml

@@ -5,6 +5,7 @@
 	</brief_description>
 	<description>
 		Navigation2D provides navigation and pathfinding within a 2D area, specified as a collection of [NavigationPolygon] resources. By default, these are automatically collected from child [NavigationPolygonInstance] nodes, but they can also be added on the fly with [method navpoly_add].
+		[b]Note:[/b] The current navigation system has many known issues and will not always return optimal paths as expected. These issues will be fixed in Godot 4.0.
 	</description>
 	<tutorials>
 		<link title="2D Navigation Demo">https://godotengine.org/asset-library/asset/117</link>
@@ -39,6 +40,7 @@
 			</argument>
 			<description>
 				Returns the path between two given points. Points are in local coordinate space. If [code]optimize[/code] is [code]true[/code] (the default), the path is smoothed by merging path segments where possible.
+				[b]Note:[/b] This method has known issues and will often return non-optimal paths. These issues will be fixed in Godot 4.0.
 			</description>
 		</method>
 		<method name="navpoly_add">