Improve the Shape/Shape2D classes documentation

8 files changed, 37 insertions, 6 deletions

diff --git a/doc/classes/CollisionShape2D.xml b/doc/classes/CollisionShape2D.xml
index 5fd8826a98..4166ee31d3 100644
--- a/doc/classes/CollisionShape2D.xml
+++ b/doc/classes/CollisionShape2D.xml
@@ -19,6 +19,7 @@
 			Sets whether this collision shape should only detect collision on one side (top or bottom).
 		</member>
 		<member name="one_way_collision_margin" type="float" setter="set_one_way_collision_margin" getter="get_one_way_collision_margin" default="1.0">
+			The margin used for one-way collision (in pixels).
 		</member>
 		<member name="shape" type="Shape2D" setter="set_shape" getter="get_shape">
 			The actual shape owned by this collision shape.
diff --git a/doc/classes/Physics2DShapeQueryParameters.xml b/doc/classes/Physics2DShapeQueryParameters.xml
index 7d46dd2876..7ea00cbddc 100644
--- a/doc/classes/Physics2DShapeQueryParameters.xml
+++ b/doc/classes/Physics2DShapeQueryParameters.xml
@@ -4,7 +4,7 @@
 		Parameters to be sent to a 2D shape physics query.
 	</brief_description>
 	<description>
-		This class contains the shape and other parameters for intersection/collision queries.
+		This class contains the shape and other parameters for 2D intersection/collision queries. See also [Physics2DShapeQueryResult].
 	</description>
 	<tutorials>
 	</tutorials>
@@ -21,14 +21,16 @@
 	</methods>
 	<members>
 		<member name="collide_with_areas" type="bool" setter="set_collide_with_areas" getter="is_collide_with_areas_enabled" default="false">
+			If [code]true[/code], the query will take [Area2D]s into account.
 		</member>
 		<member name="collide_with_bodies" type="bool" setter="set_collide_with_bodies" getter="is_collide_with_bodies_enabled" default="true">
+			If [code]true[/code], the query will take [PhysicsBody2D]s into account.
 		</member>
 		<member name="collision_layer" type="int" setter="set_collision_layer" getter="get_collision_layer" default="2147483647">
-			The physics layer the query should be made on.
+			The physics layer(s) the query will take into account (as a bitmask).
 		</member>
 		<member name="exclude" type="Array" setter="set_exclude" getter="get_exclude" default="[  ]">
-			The list of objects or object [RID]s, that will be excluded from collisions.
+			The list of objects or object [RID]s that will be excluded from collisions.
 		</member>
 		<member name="margin" type="float" setter="set_margin" getter="get_margin" default="0.0">
 			The collision margin for the shape.
@@ -37,10 +39,10 @@
 			The motion of the shape being queried for.
 		</member>
 		<member name="shape_rid" type="RID" setter="set_shape_rid" getter="get_shape_rid">
-			The [RID] of the queried shape. See also [method set_shape].
+			The queried shape's [RID]. See also [method set_shape].
 		</member>
 		<member name="transform" type="Transform2D" setter="set_transform" getter="get_transform" default="Transform2D( 1, 0, 0, 1, 0, 0 )">
-			the transform matrix of the queried shape.
+			The queried shape's transform matrix.
 		</member>
 	</members>
 	<constants>
diff --git a/doc/classes/Physics2DShapeQueryResult.xml b/doc/classes/Physics2DShapeQueryResult.xml
index dd38b488f5..06f943cb6d 100644
--- a/doc/classes/Physics2DShapeQueryResult.xml
+++ b/doc/classes/Physics2DShapeQueryResult.xml
@@ -1,8 +1,10 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="Physics2DShapeQueryResult" inherits="Reference" category="Core" version="3.2">
 	<brief_description>
+		Result of a 2D shape query in [Physics2DServer].
 	</brief_description>
 	<description>
+		The result of a 2D shape query in [Physics2DServer]. See also [Physics2DShapeQueryParameters].
 	</description>
 	<tutorials>
 	</tutorials>
@@ -11,6 +13,7 @@
 			<return type="int">
 			</return>
 			<description>
+				Returns the number of objects that intersected with the shape.
 			</description>
 		</method>
 		<method name="get_result_object" qualifiers="const">
@@ -19,6 +22,7 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+				Returns the [Object] that intersected with the shape at index [code]idx[/code].
 			</description>
 		</method>
 		<method name="get_result_object_id" qualifiers="const">
@@ -27,6 +31,7 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+				Returns the instance ID of the [Object] that intersected with the shape at index [code]idx[/code].
 			</description>
 		</method>
 		<method name="get_result_object_shape" qualifiers="const">
@@ -35,6 +40,7 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+				Returns the child index of the object's [Shape] that intersected with the shape at index [code]idx[/code].
 			</description>
 		</method>
 		<method name="get_result_rid" qualifiers="const">
@@ -43,6 +49,7 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+				Returns the [RID] of the object that intersected with the shape at index [code]idx[/code].
 			</description>
 		</method>
 	</methods>
diff --git a/doc/classes/PhysicsShapeQueryParameters.xml b/doc/classes/PhysicsShapeQueryParameters.xml
index 7d7307592e..d56247fcaf 100644
--- a/doc/classes/PhysicsShapeQueryParameters.xml
+++ b/doc/classes/PhysicsShapeQueryParameters.xml
@@ -1,8 +1,10 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="PhysicsShapeQueryParameters" inherits="Reference" category="Core" version="3.2">
 	<brief_description>
+		Parameters to be sent to a 3D shape physics query.
 	</brief_description>
 	<description>
+		This class contains the shape and other parameters for 3D intersection/collision queries. See also [PhysicsShapeQueryResult].
 	</description>
 	<tutorials>
 	</tutorials>
@@ -13,23 +15,31 @@
 			<argument index="0" name="shape" type="Resource">
 			</argument>
 			<description>
+				Sets the [Shape] that will be used for collision/intersection queries.
 			</description>
 		</method>
 	</methods>
 	<members>
 		<member name="collide_with_areas" type="bool" setter="set_collide_with_areas" getter="is_collide_with_areas_enabled" default="false">
+			If [code]true[/code], the query will take [Area]s into account.
 		</member>
 		<member name="collide_with_bodies" type="bool" setter="set_collide_with_bodies" getter="is_collide_with_bodies_enabled" default="true">
+			If [code]true[/code], the query will take [PhysicsBody]s into account.
 		</member>
 		<member name="collision_mask" type="int" setter="set_collision_mask" getter="get_collision_mask" default="2147483647">
+			The physics layer(s) the query will take into account (as a bitmask).
 		</member>
 		<member name="exclude" type="Array" setter="set_exclude" getter="get_exclude" default="[  ]">
+			The list of objects or object [RID]s that will be excluded from collisions.
 		</member>
 		<member name="margin" type="float" setter="set_margin" getter="get_margin" default="0.0">
+			The collision margin for the shape.
 		</member>
 		<member name="shape_rid" type="RID" setter="set_shape_rid" getter="get_shape_rid">
+			The queried shape's [RID]. See also [method set_shape].
 		</member>
 		<member name="transform" type="Transform" setter="set_transform" getter="get_transform" default="Transform( 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0 )">
+			The queried shape's transform matrix.
 		</member>
 	</members>
 	<constants>
diff --git a/doc/classes/PhysicsShapeQueryResult.xml b/doc/classes/PhysicsShapeQueryResult.xml
index 92a4393979..1f151ebb1a 100644
--- a/doc/classes/PhysicsShapeQueryResult.xml
+++ b/doc/classes/PhysicsShapeQueryResult.xml
@@ -1,9 +1,10 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="PhysicsShapeQueryResult" inherits="Reference" category="Core" version="3.2">
 	<brief_description>
-		Result of a shape query in Physics2DServer.
+		Result of a 3D shape query in [PhysicsServer].
 	</brief_description>
 	<description>
+		The result of a 3D shape query in [PhysicsServer]. See also [PhysicsShapeQueryParameters].
 	</description>
 	<tutorials>
 	</tutorials>
@@ -12,6 +13,7 @@
 			<return type="int">
 			</return>
 			<description>
+				Returns the number of objects that intersected with the shape.
 			</description>
 		</method>
 		<method name="get_result_object" qualifiers="const">
@@ -20,6 +22,7 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+				Returns the [Object] that intersected with the shape at index [code]idx[/code].
 			</description>
 		</method>
 		<method name="get_result_object_id" qualifiers="const">
@@ -28,6 +31,7 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+				Returns the instance ID of the [Object] that intersected with the shape at index [code]idx[/code].
 			</description>
 		</method>
 		<method name="get_result_object_shape" qualifiers="const">
@@ -36,6 +40,7 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+				Returns the child index of the object's [Shape] that intersected with the shape at index [code]idx[/code].
 			</description>
 		</method>
 		<method name="get_result_rid" qualifiers="const">
@@ -44,6 +49,7 @@
 			<argument index="0" name="idx" type="int">
 			</argument>
 			<description>
+				Returns the [RID] of the object that intersected with the shape at index [code]idx[/code].
 			</description>
 		</method>
 	</methods>
diff --git a/doc/classes/PlaneShape.xml b/doc/classes/PlaneShape.xml
index b94bb8e613..ee841a3cff 100644
--- a/doc/classes/PlaneShape.xml
+++ b/doc/classes/PlaneShape.xml
@@ -1,8 +1,10 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="PlaneShape" inherits="Shape" category="Core" version="3.2">
 	<brief_description>
+		Infinite plane shape for 3D collisions.
 	</brief_description>
 	<description>
+		An infinite plane shape for 3D collisions. Note that the [Plane]'s normal matters; anything "below" the plane will collide with it. If the [PlaneShape] is used in a [PhysicsBody], it will cause colliding objects placed "below" it to teleport "above" the plane.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -10,6 +12,7 @@
 	</methods>
 	<members>
 		<member name="plane" type="Plane" setter="set_plane" getter="get_plane" default="Plane( 0, 1, 0, 0 )">
+			The [Plane] used by the [PlaneShape] for collision.
 		</member>
 	</members>
 	<constants>
diff --git a/doc/classes/Shape.xml b/doc/classes/Shape.xml
index ce5947bc06..123353b59a 100644
--- a/doc/classes/Shape.xml
+++ b/doc/classes/Shape.xml
@@ -13,6 +13,7 @@
 	</methods>
 	<members>
 		<member name="margin" type="float" setter="set_margin" getter="get_margin" default="0.04">
+			The collision margin for the shape.
 		</member>
 	</members>
 	<constants>
diff --git a/doc/classes/Shape2D.xml b/doc/classes/Shape2D.xml
index 2c3120f04d..70d55344ca 100644
--- a/doc/classes/Shape2D.xml
+++ b/doc/classes/Shape2D.xml
@@ -77,6 +77,7 @@
 	</methods>
 	<members>
 		<member name="custom_solver_bias" type="float" setter="set_custom_solver_bias" getter="get_custom_solver_bias" default="0.0">
+			The shape's custom solver bias.
 		</member>
 	</members>
 	<constants>