Inserted explanation about the behaviour of CollsionPolygon2D.set_polygon.

1 files changed, 43 insertions, 12 deletions

diff --git a/doc/base/classes.xml b/doc/base/classes.xml
index d1be39fe43..32ff75efbd 100644
--- a/doc/base/classes.xml
+++ b/doc/base/classes.xml
@@ -6947,7 +6947,7 @@
 	Base node for 2D collisionables.
 	</brief_description>
 	<description>
-	CollisionObject2D is the base class for 2D physics collisionables. They can hold any number of 2D collision shapes. Usually, they are edited by placing CollisionBody2D and CollisionPolygon2D nodes as children. Such nodes are for reference ant not present outside the editor, so code should use the regular shape API.
+	CollisionObject2D is the base class for 2D physics collisionables. They can hold any number of 2D collision shapes. Usually, they are edited by placing [CollisionBody2D] and [CollisionPolygon2D] nodes as children. Such nodes are for reference and not present outside the editor, so code should use the regular shape API.
 	</description>
 	<methods>
 		<method name="_input_event" qualifiers="virtual">
@@ -7143,58 +7143,69 @@
 </class>
 <class name="CollisionPolygon2D" inherits="Node2D" category="Core">
 	<brief_description>
-	Editor-Only class.
+	Editor-only class for easy editing of collision polygons.
 	</brief_description>
 	<description>
-	Editor-Only class. This is not present when running the game. It's used in the editor to properly edit and position collision shapes in [CollisionObject2D]. This is not accessible from regular code. This class is for editing custom shape polygons.
+	Editor-only class. This is not present when running the game. It's used in the editor to properly edit and position collision shapes in [CollisionObject2D]. This is not accessible from regular code. This class is for editing custom shape polygons.
 	</description>
 	<methods>
 		<method name="set_polygon">
 			<argument index="0" name="polygon" type="Vector2Array">
 			</argument>
 			<description>
+			Set the array of points forming the polygon.
+			When editing the point list via the editor, depending on [method get_build_mode], it has to be a list of points (for [code]build_mode[/code]=0), or a list of lines (for [code]build_mode[/code]=1). In the second case, the even elements of the array define the start point of the line, and the odd elements the end point.
 			</description>
 		</method>
 		<method name="get_polygon" qualifiers="const">
 			<return type="Vector2Array">
 			</return>
 			<description>
+			Return the list of points that define the polygon.
 			</description>
 		</method>
 		<method name="set_build_mode">
-			<argument index="0" name="arg0" type="int">
+			<argument index="0" name="build_mode" type="int">
 			</argument>
 			<description>
+			Set whether the polygon is to be a [ConvexPolygon2D] ([code]build_mode[/code]=0), or a [ConcavePolygon2D] ([code]build_mode[/code]=1).
 			</description>
 		</method>
 		<method name="get_build_mode" qualifiers="const">
 			<return type="int">
 			</return>
 			<description>
+			Return whether the polygon is a [ConvexPolygon2D] ([code]build_mode[/code]=0), or a [ConcavePolygon2D] ([code]build_mode[/code]=1).
 			</description>
 		</method>
 		<method name="set_trigger">
-			<argument index="0" name="arg0" type="bool">
+			<argument index="0" name="enable" type="bool">
 			</argument>
 			<description>
+			Set whether this polygon is a trigger. A trigger polygon detects collisions, but is otherwise unaffected by physics (i.e. colliding objects will not get blocked).
 			</description>
 		</method>
 		<method name="is_trigger" qualifiers="const">
 			<return type="bool">
 			</return>
 			<description>
+			Return whether this polygon is a trigger.
 			</description>
 		</method>
 		<method name="get_collision_object_first_shape" qualifiers="const">
 			<return type="int">
 			</return>
 			<description>
+			Return the index of the first shape generated by the editor.
+			When [code]build_mode[/code] is set to generate convex polygons, the shape shown in the editor may be decomopsed into many convex polygons. In that case, a range of indexes is needed to directly access the [Shape2D]s.
+			When [code]build_mode[/code] is set to generate concave polygons, there is only one [Shape2D] generated, so the start index and the end index are the same.
 			</description>
 		</method>
 		<method name="get_collision_object_last_shape" qualifiers="const">
 			<return type="int">
 			</return>
 			<description>
+			Return the index of the last shape generated by the editor.
 			</description>
 		</method>
 	</methods>
@@ -7253,40 +7264,45 @@
 </class>
 <class name="CollisionShape2D" inherits="Node2D" category="Core">
 	<brief_description>
-	Editor-Only class.
+	Editor-only class for easy editing of shapes.
 	</brief_description>
 	<description>
-	Editor-Only class. This is not present when running the game. It's used in the editor to properly edit and position collision shapes in [CollisionObject2D]. This is not accessible from regular code.
+	Editor-only class. This is not present when running the game. It's used in the editor to properly edit and position collision shapes in [CollisionObject2D]. This is not accessible from regular code.
 	</description>
 	<methods>
 		<method name="set_shape">
 			<argument index="0" name="shape" type="Object">
 			</argument>
 			<description>
+			Set this shape's [Shape2D]. This will not appear as a node, but can be directly edited as a property.
 			</description>
 		</method>
 		<method name="get_shape" qualifiers="const">
 			<return type="Object">
 			</return>
 			<description>
+			Return this shape's [Shape2D].
 			</description>
 		</method>
 		<method name="set_trigger">
 			<argument index="0" name="enable" type="bool">
 			</argument>
 			<description>
+			Set whether this shape is a trigger. A trigger shape detects collisions, but is otherwise unaffected by physics (i.e. will not block movement of colliding objects).
 			</description>
 		</method>
 		<method name="is_trigger" qualifiers="const">
 			<return type="bool">
 			</return>
 			<description>
+			Return whether this shape is a trigger.
 			</description>
 		</method>
 		<method name="get_collision_object_shape_index" qualifiers="const">
 			<return type="int">
 			</return>
 			<description>
+			Return the index of this shape inside its container [CollisionObject2D]. This can be used to directly access the underlying [Shape2D].
 			</description>
 		</method>
 	</methods>
@@ -7693,6 +7709,7 @@
 	</brief_description>
 	<description>
 	Concave polygon 2D shape resource for physics. It is made out of segments and is very optimal for complex polygonal concave collisions. It is really not advised to use for RigidBody nodes. A CollisionPolygon2D in convex decomposition mode (solids) or several convex objects are advised for that instead. Otherwise, a concave polygon 2D shape is better for static collisions.
+	The main difference between a [ConvexPolygonShape2D] and a [ConcavePolygonShape2D] is that a concave polygon assumes it is concave and uses a more complex method of collision detection, and a convex one forces itself to be convex in order to speed up collision detection.
 	</description>
 	<methods>
 		<method name="set_segments">
@@ -8583,8 +8600,8 @@
 	Convex Polygon Shape for 2D physics.
 	</brief_description>
 	<description>
-	Convex Polygon Shape for 2D physics. A convex polygon
-	Concave polygon 2D shape resource for physics. It is made out of segments and is very optimal for complex polygonal concave collisions. It is really not advised to use for RigidBody nodes. A CollisionPolygon2D in convex decomposition mode (solids) or several convex objects are advised for that instead. Otherwise, a concave polygon 2D shape is better for static collisions.
+	Convex Polygon Shape for 2D physics. A convex polygon, whatever its shape, is internally decomposed into as many convex polygons as needed to ensure all collision checks against it are always done on convex polygons (which are faster to check).
+	The main difference between a [ConvexPolygonShape2D] and a [ConcavePolygonShape2D] is that a concave polygon assumes it is concave and uses a more complex method of collision detection, and a convex one forces itself to be convex in order to speed up collision detection.
 	</description>
 	<methods>
 		<method name="set_point_cloud">
@@ -26585,19 +26602,21 @@ This method controls whether the position between two cached points is interpola
 	Ray 2D shape resource for physics.
 	</brief_description>
 	<description>
-	Ray 2D shape resource for physics. A ray is not really a collision body, isntead it tries to separate itself from whatever is touching its far endpoint. It's often useful for ccharacters.
+	Ray 2D shape resource for physics. A ray is not really a collision body, isntead it tries to separate itself from whatever is touching its far endpoint. It's often useful for characters.
 	</description>
 	<methods>
 		<method name="set_length">
 			<argument index="0" name="length" type="float">
 			</argument>
 			<description>
+			Set the length of the ray.
 			</description>
 		</method>
 		<method name="get_length" qualifiers="const">
 			<return type="float">
 			</return>
 			<description>
+			Return the length of the ray.
 			</description>
 		</method>
 	</methods>
@@ -29544,24 +29563,28 @@ This method controls whether the position between two cached points is interpola
 			<argument index="0" name="a" type="Vector2">
 			</argument>
 			<description>
+			Set the first point's position.
 			</description>
 		</method>
 		<method name="get_a" qualifiers="const">
 			<return type="Vector2">
 			</return>
 			<description>
+			Return the first point's position.
 			</description>
 		</method>
 		<method name="set_b">
 			<argument index="0" name="b" type="Vector2">
 			</argument>
 			<description>
+			Set the second point's position.
 			</description>
 		</method>
 		<method name="get_b" qualifiers="const">
 			<return type="Vector2">
 			</return>
 			<description>
+			Return the second point's position.
 			</description>
 		</method>
 	</methods>
@@ -30609,14 +30632,14 @@ This method controls whether the position between two cached points is interpola
 			</argument>
 			<description>
 			Use a custom solver bias. No need to change this unless you really know what you are doing.
-			The solver bias is a factor controlling how much two colliding objects "rebound" off each other, to avoid them getting into each other, because of numerical imprecision.
+			The solver bias is a factor controlling how much two objects "rebound" off each other, when colliding, to avoid them getting into each other because of numerical imprecision.
 			</description>
 		</method>
 		<method name="get_custom_solver_bias" qualifiers="const">
 			<return type="float">
 			</return>
 			<description>
-			Return the custom solver bias. No need to change this unless you really know what you are doing.
+			Return the custom solver bias.
 			</description>
 		</method>
 		<method name="collide">
@@ -30629,6 +30652,8 @@ This method controls whether the position between two cached points is interpola
 			<argument index="2" name="shape_xform" type="Matrix32">
 			</argument>
 			<description>
+			Return whether this shape is colliding with another.
+			This method needs the transformation matrix for this shape ([code]local_xform[/code]), the shape to check collisions with ([code]with_shape[/code]), and the transformation matrix of that shape ([code]shape_xform[/code]).
 			</description>
 		</method>
 		<method name="collide_with_motion">
@@ -30645,6 +30670,8 @@ This method controls whether the position between two cached points is interpola
 			<argument index="4" name="shape_motion" type="Vector2">
 			</argument>
 			<description>
+			Return whether this shape would collide with another, if a given movemen was applied.
+			This method needs the transformation matrix for this shape ([code]local_xform[/code]), the movement to test on this shape ([code]local_motion[/code]), the shape to check collisions with ([code]with_shape[/code]), the transformation matrix of that shape ([code]shape_xform[/code]), and the movement to test ont the other object ([code]shape_motion[/code]).
 			</description>
 		</method>
 		<method name="collide_and_get_contacts">
@@ -30657,6 +30684,8 @@ This method controls whether the position between two cached points is interpola
 			<argument index="2" name="shape_xform" type="Matrix32">
 			</argument>
 			<description>
+			Return a list of the points where this shape touches another. If there are no collisions, the list is empty.
+			This method needs the transformation matrix for this shape ([code]local_xform[/code]), the shape to check collisions with ([code]with_shape[/code]), and the transformation matrix of that shape ([code]shape_xform[/code]).
 			</description>
 		</method>
 		<method name="collide_with_motion_and_get_contacts">
@@ -30673,6 +30702,8 @@ This method controls whether the position between two cached points is interpola
 			<argument index="4" name="shape_motion" type="Vector2">
 			</argument>
 			<description>
+			Return a list of the points where this shape would touch another, if a given movement was applied. If there are no collisions, the list is empty.
+			This method needs the transformation matrix for this shape ([code]local_xform[/code]), the movement to test on this shape ([code]local_motion[/code]), the shape to check collisions with ([code]with_shape[/code]), the transformation matrix of that shape ([code]shape_xform[/code]), and the movement to test ont the other object ([code]shape_motion[/code]).
 			</description>
 		</method>
 	</methods>