From 69017974beb16dcfa971f9b6f33a4f005be57bef Mon Sep 17 00:00:00 2001
From: Franco Falleti <ezefran256@gmail.com>
Date: Tue, 12 Sep 2017 10:02:57 -0300
Subject: Document AStar (#11056)

Add code examples
---
 doc/base/classes.xml | 71 ++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 58 insertions(+), 13 deletions(-)

diff --git a/doc/base/classes.xml b/doc/base/classes.xml
index 323ec8106d..a8e877ccd5 100644
--- a/doc/base/classes.xml
+++ b/doc/base/classes.xml
@@ -2881,6 +2881,7 @@
 			<argument index="1" name="to_id" type="int">
 			</argument>
 			<description>
+				Called when computing the cost between two connected points.
 			</description>
 		</method>
 		<method name="_estimate_cost" qualifiers="virtual">
@@ -2891,6 +2892,7 @@
 			<argument index="1" name="to_id" type="int">
 			</argument>
 			<description>
+				Called when estimating the cost between a point and the path's ending point. 
 			</description>
 		</method>
 		<method name="add_point">
@@ -2903,7 +2905,12 @@
 			<argument index="2" name="weight_scale" type="float" default="1.0">
 			</argument>
 			<description>
-				Add a new point at the given position [code]pos[/code] with the given identifier [code]id[/code]. The [code]weight_scale[/code] has to be 1 or larger.
+				Adds a new point at the given position with the given identifier. The algorithm prefers points with lower [code]weight_scale[/code] to form a path. The [code]id[/code] must be 0 or larger, and the [code]weight_scale[/code] must be 1 or larger.
+				[codeblock]
+				var as = AStar.new()
+				
+				as.add_point(1, Vector3(1,0,0), 4) # Adds the point (1,0,0) with weight_scale=4 and id=1
+				[/codeblock]
 			</description>
 		</method>
 		<method name="are_points_connected" qualifiers="const">
@@ -2914,14 +2921,14 @@
 			<argument index="1" name="to_id" type="int">
 			</argument>
 			<description>
-				Returns if there is a connection/segment between points [code]id[/code] and [code]from_id[/code]
+				Returns whether there is a connection/segment between the given points.
 			</description>
 		</method>
 		<method name="clear">
 			<return type="void">
 			</return>
 			<description>
-				Clear all the points and segments from AStar instance.
+				Clears all the points and segments.
 			</description>
 		</method>
 		<method name="connect_points">
@@ -2934,7 +2941,16 @@
 			<argument index="2" name="bidirectional" type="bool" default="true">
 			</argument>
 			<description>
-				Create a segment between points [code]id[/code] and [code]to_id[/code].
+				Creates a segment between the given points.
+				[codeblock]
+				var as = AStar.new()
+				
+				as.add_point(1, Vector3(1,1,0))
+				as.add_point(2, Vector3(0,5,0))
+				
+				as.connect_points(1, 2, false) # If bidirectional=false it's only possible to go from point 1 to point 2
+				                               # and not from point 2 to point 1.
+				[/codeblock]
 			</description>
 		</method>
 		<method name="disconnect_points">
@@ -2945,13 +2961,14 @@
 			<argument index="1" name="to_id" type="int">
 			</argument>
 			<description>
-				Deletes a segment between points [code]id[/code] and [code]to_id[/code].
+				Deletes the segment between the given points.
 			</description>
 		</method>
 		<method name="get_available_point_id" qualifiers="const">
 			<return type="int">
 			</return>
 			<description>
+				Returns an id with no point associated to it.
 			</description>
 		</method>
 		<method name="get_closest_point" qualifiers="const">
@@ -2960,7 +2977,7 @@
 			<argument index="0" name="to_pos" type="Vector3">
 			</argument>
 			<description>
-				Returns the id of closest point of given point.  -1 is returned if there are no points on AStar.
+				Returns the id of the closest point to [code]to_pos[/code]. Returns -1 if there are no points in the points pool.
 			</description>
 		</method>
 		<method name="get_closest_pos_in_segment" qualifiers="const">
@@ -2969,7 +2986,18 @@
 			<argument index="0" name="to_pos" type="Vector3">
 			</argument>
 			<description>
-				Returns the position of closest point that has segments.
+				Returns the closest position to [code]to_pos[/code] that resides inside a segment between two connected points.
+				[codeblock]
+				var as = AStar.new()
+				
+				as.add_point(1, Vector3(0,0,0))
+				as.add_point(2, Vector3(0,5,0))
+				
+				as.connect_points(1, 2)
+				
+				var res = as.get_closest_pos_in_segment(Vector3(3,3,0)) # returns (0, 3, 0)
+				[/codeblock]
+				The result is in the segment that goes from [code]y=0[/code] to [code]y=5[/code]. It's the closest position in the segment to the given point.
 			</description>
 		</method>
 		<method name="get_id_path">
@@ -2980,7 +3008,24 @@
 			<argument index="1" name="to_id" type="int">
 			</argument>
 			<description>
-				Returns an array with the point ids of path found by AStar between two given points.
+				Returns an array with the ids of the points that form the path found by AStar between the given points. The array is ordered from the starting point to the ending point of the path.
+				[codeblock]
+				var as = AStar.new()
+				
+				as.add_point(1, Vector3(0,0,0))
+				as.add_point(2, Vector3(0,1,0), 1) # default weight is 1
+				as.add_point(3, Vector3(1,1,0))
+				as.add_point(4, Vector3(2,0,0))
+				
+				as.connect_points(1, 2, false)
+				as.connect_points(2, 3, false)
+				as.connect_points(4, 3, false)
+				as.connect_points(1, 4, false)
+				as.connect_points(5, 4, false)
+				
+				var res = as.get_id_path(1, 3) # returns [1, 2, 3]
+				[/codeblock]
+				If you change the 2nd point's weight to 3, then the result will be [code][1, 4, 3][/code] instead, because now even though the distance is longer, it's "easier" to get through point 4 than through point 2.
 			</description>
 		</method>
 		<method name="get_point_path">
@@ -2991,7 +3036,7 @@
 			<argument index="1" name="to_id" type="int">
 			</argument>
 			<description>
-				Returns an array with the points of path found by AStar between two given points.
+				Returns an array with the points that are in the path found by AStar between the given points. The array is ordered from the starting point to the ending point of the path.
 			</description>
 		</method>
 		<method name="get_point_pos" qualifiers="const">
@@ -3000,7 +3045,7 @@
 			<argument index="0" name="id" type="int">
 			</argument>
 			<description>
-				Returns the position of point with given id.
+				Returns the position of the point associated with the given id.
 			</description>
 		</method>
 		<method name="get_point_weight_scale" qualifiers="const">
@@ -3009,7 +3054,7 @@
 			<argument index="0" name="id" type="int">
 			</argument>
 			<description>
-				Returns the weight scale of point with given id.
+				Returns the weight scale of the point associated with the given id.
 			</description>
 		</method>
 		<method name="has_point" qualifiers="const">
@@ -3018,7 +3063,7 @@
 			<argument index="0" name="id" type="int">
 			</argument>
 			<description>
-				Returns if the point with given id exists on AStar;
+				Returns whether a point associated with the given id exists.
 			</description>
 		</method>
 		<method name="remove_point">
@@ -3027,7 +3072,7 @@
 			<argument index="0" name="id" type="int">
 			</argument>
 			<description>
-				Removes the point with given id.
+				Removes the point associated with the given id from the points pool.
 			</description>
 		</method>
 	</methods>
-- 
cgit v1.2.3