From 6d27c50ae7e934afc6ad6f19a030fc2512e825e6 Mon Sep 17 00:00:00 2001
From: QbieShay <cislaghi.ilaria@gmail.com>
Date: Sat, 9 Nov 2019 19:16:08 +0100
Subject: [PATCH] Added documentation for SpringArm doc

---
 doc/classes/SpringArm.xml | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/doc/classes/SpringArm.xml b/doc/classes/SpringArm.xml
index 438d96f2b33..133ff688592 100644
--- a/doc/classes/SpringArm.xml
+++ b/doc/classes/SpringArm.xml
@@ -1,8 +1,13 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="SpringArm" inherits="Spatial" category="Core" version="3.2">
 	<brief_description>
+		A helper node, mostly used in 3rd person cameras.
 	</brief_description>
 	<description>
+		The SpringArm node is a node that casts a ray (or collision shape) along its z axis and moves all its direct children to the collision point, minus a margin.
+		The most common use case for this is to make a 3rd person camera that reacts to collisions in the environment.
+		The SpringArm will either cast a ray, or if a shape is given, it will cast the shape in the direction of its z axis.
+		If you use the SpringArm as a camera controller for your player, you might need to exclude the player's collider from the SpringArm's collision check.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -13,18 +18,21 @@
 			<argument index="0" name="RID" type="RID">
 			</argument>
 			<description>
+				Adds the object with the given [RID] to the list of objects excluded from the collision check.
 			</description>
 		</method>
 		<method name="clear_excluded_objects">
 			<return type="void">
 			</return>
 			<description>
+				Clears the list of objects excluded from the collision check.
 			</description>
 		</method>
 		<method name="get_hit_length">
 			<return type="float">
 			</return>
 			<description>
+				Returns the proportion between the current arm length (after checking for collisions) and the [member spring_length]. Ranges from 0 to 1.
 			</description>
 		</method>
 		<method name="remove_excluded_object">
@@ -33,17 +41,26 @@
 			<argument index="0" name="RID" type="RID">
 			</argument>
 			<description>
+				Removes the given [RID] from the list of objects excluded from the collision check.
 			</description>
 		</method>
 	</methods>
 	<members>
 		<member name="collision_mask" type="int" setter="set_collision_mask" getter="get_collision_mask" default="1">
+			The layers against which the collision check shall be done.
 		</member>
 		<member name="margin" type="float" setter="set_margin" getter="get_margin" default="0.01">
+			When the collision check is made, a candidate length for the SpringArm is given.
+			The margin is then subtracted to this length and the translation is applied to the child objects of the SpringArm.
+			This margin is useful for when the SpringArm has a [Camera] as a child node: without the margin, the [Camera] would be placed on the exact point of collision, while with the margin the [Camera] would be placed close to the point of collision.
 		</member>
 		<member name="shape" type="Shape" setter="set_shape" getter="get_shape">
+			The [Shape] to use for the SpringArm.
+			When the shape is set, the SpringArm will cast the [Shape] on its z axis instead of performing a ray cast.
 		</member>
 		<member name="spring_length" type="float" setter="set_length" getter="get_length" default="1.0">
+			The maximum extent of the SpringArm. This is used as a length for both the ray and the shape cast used internally to calculate the desired position of the SpringArm's child nodes.
+			To know more about how to perform a shape cast or a ray cast, please consult the [PhysicsDirectSpaceState] documentation.
 		</member>
 	</members>
 	<constants>