docs: XML Comments added for Bepu Constraints (#2633)

* docs: XML Comments added

* docs: XML comments added for CenterDistanceLimitConstraintComponent.cs

* fix: XML comment wording corrected

* docs: XML comment added for CenterDistanceConstraintComponent

* feat: XML comments added for BallSocketConstraintComponent.cs

* docs: XML comments improvements

* docs: XML comment updated

* fix: Duplicated summary removed

* docs: XML comments improvements

* docs: XML comments improvements

* docs: XML comments improvements

Author: VaclavElias

sources/engine/Stride.BepuPhysics/Stride.BepuPhysics/Constraints/BallSocketConstraintComponent.cs

@@ -2,7 +2,6 @@
 // Distributed under the MIT license. See the LICENSE.md file in the project root for more information.
 
 using BepuPhysics.Constraints;
-using Stride.BepuPhysics.Definitions;
 using Stride.BepuPhysics.Systems;
 using Stride.Core;
 using Stride.Core.Mathematics;
@@ -11,13 +10,33 @@
 
 namespace Stride.BepuPhysics.Constraints;
 
+/// <summary>
+/// Creates a spherical joint (also known as a ball and socket joint) that constrains two bodies to share a connection point.
+/// <para>
+/// This constraint keeps a specific point on body A (defined by <see cref="LocalOffsetA"/>) coincident with a specific point
+/// on body B (defined by <see cref="LocalOffsetB"/>), while still allowing full rotational freedom around the connection point.
+/// </para>
+/// <para>
+/// Common uses include:
+/// <list type="bullet">
+/// <item>Character joint connections (shoulders, hips, etc.)</item>
+/// <item>Chain links</item>
+/// <item>Pendulums</item>
+/// <item>Rag doll physics</item>
+/// <item>Cloth and soft body simulation</item>
+/// </list>
+/// </para>
+/// </summary>
 [DataContract]
 [DefaultEntityComponentProcessor(typeof(ConstraintProcessor), ExecutionMode = ExecutionMode.Runtime)]
 [ComponentCategory("Physics - Bepu Constraint")]
 public sealed class BallSocketConstraintComponent : TwoBodyConstraintComponent<BallSocket>
 {
     public BallSocketConstraintComponent() => BepuConstraint = new() { SpringSettings = new SpringSettings(30, 5) };
 
+    /// <summary>
+    /// Offset from the center of body A to its attachment in A's local space.
+    /// </summary>
     public Vector3 LocalOffsetA
     {
         get
@@ -31,6 +50,9 @@ public Vector3 LocalOffsetA
         }
     }
 
+    /// <summary>
+    /// Offset from the center of body B to its attachment in B's local space.
+    /// </summary>
     public Vector3 LocalOffsetB
     {
         get
@@ -44,6 +66,10 @@ public Vector3 LocalOffsetB
         }
     }
 
+    /// <summary>
+    /// Gets or sets the target number of undamped oscillations per unit of time.
+    /// Higher frequency values create stiffer connections, while lower values allow more elasticity in the joint.
+    /// </summary>
     public float SpringFrequency
     {
         get
@@ -57,6 +83,10 @@ public float SpringFrequency
         }
     }
 
+    /// <summary>
+    /// Gets or sets the ratio of the spring's actual damping to its critical damping. 0 is undamped, 1 is critically damped, and higher values are overdamped.
+    /// Higher damping ratios reduce oscillations and make the connection less elastic.
+    /// </summary>
     public float SpringDampingRatio
     {
         get

sources/engine/Stride.BepuPhysics/Stride.BepuPhysics/Constraints/CenterDistanceConstraintComponent.cs

@@ -9,13 +9,27 @@
 
 namespace Stride.BepuPhysics.Constraints;
 
+/// <summary>
+/// Constrains the center of two bodies to be separated by a target distance.
+/// This constraint ensures that the distance between the center points of two bodies
+/// attempts to match a specific target value. Unlike <see cref="DistanceServoConstraintComponent"/>,
+/// this constraint operates directly on the body centers rather than on specific points on the bodies.
+/// </summary>
+/// <remarks>
+/// This is a specialized variant of <see cref="DistanceServoConstraintComponent"/> that works with body centers.
+/// Use this when you need to constrain the distance between bodies without specifying exact attachment points.
+/// For a version that allows a range of distances rather than a single target value, see <see cref="CenterDistanceLimitConstraintComponent"/>.
+/// </remarks>
 [DataContract]
 [DefaultEntityComponentProcessor(typeof(ConstraintProcessor), ExecutionMode = ExecutionMode.Runtime)]
 [ComponentCategory("Physics - Bepu Constraint")]
 public sealed class CenterDistanceConstraintComponent : TwoBodyConstraintComponent<CenterDistanceConstraint>
 {
     public CenterDistanceConstraintComponent() => BepuConstraint = new() { SpringSettings = new SpringSettings(30, 5) };
 
+    /// <summary>
+    /// Target distance between the body centers.
+    /// </summary>
     public float TargetDistance
     {
         get

sources/engine/Stride.BepuPhysics/Stride.BepuPhysics/Constraints/CenterDistanceLimitConstraintComponent.cs

@@ -9,13 +9,26 @@
 
 namespace Stride.BepuPhysics.Constraints;
 
+/// <summary>
+/// Constrains the center of two bodies to be separated by a distance within a range.
+/// This constraint ensures that the distance between the center points of two bodies remains within
+/// a minimum and maximum range. Unlike <see cref="DistanceLimitConstraintComponent"/>, this constraint
+/// operates directly on the body centers rather than on specific points on the bodies.
+/// </summary>
+/// <remarks>
+/// This is a specialized variant of <see cref="DistanceLimitConstraintComponent"/> that works with body centers.
+/// Use this when you need to constrain the overall distance between bodies without specifying exact attachment points.
+/// </remarks>
 [DataContract]
 [DefaultEntityComponentProcessor(typeof(ConstraintProcessor), ExecutionMode = ExecutionMode.Runtime)]
 [ComponentCategory("Physics - Bepu Constraint")]
 public sealed class CenterDistanceLimitConstraintComponent : TwoBodyConstraintComponent<CenterDistanceLimit>
 {
     public CenterDistanceLimitConstraintComponent() => BepuConstraint = new() { SpringSettings = new SpringSettings(30, 5) };
 
+    /// <summary>
+    /// Minimum distance between the body centers.
+    /// </summary>
     public float MinimumDistance
     {
         get { return BepuConstraint.MinimumDistance; }
@@ -26,6 +39,9 @@ public float MinimumDistance
         }
     }
 
+    /// <summary>
+    /// Maximum distance between the body centers.
+    /// </summary>
     public float MaximumDistance
     {
         get { return BepuConstraint.MaximumDistance; }

sources/engine/Stride.BepuPhysics/Stride.BepuPhysics/Constraints/DistanceLimitConstraintComponent.cs

@@ -2,7 +2,6 @@
 // Distributed under the MIT license. See the LICENSE.md file in the project root for more information.
 
 using BepuPhysics.Constraints;
-using Stride.BepuPhysics.Definitions;
 using Stride.BepuPhysics.Systems;
 using Stride.Core;
 using Stride.Core.Mathematics;
@@ -11,13 +10,27 @@
 
 namespace Stride.BepuPhysics.Constraints;
 
+/// <summary>
+/// Constrains points on two bodies to be separated by a distance within a specified range.
+/// This constraint ensures that the distance between two points on two bodies remains within
+/// a minimum and maximum range. It is useful for creating elastic or flexible connections
+/// between bodies, where the distance can vary within the specified limits.
+/// </summary>
+/// <remarks>
+/// Unlike <see cref="CenterDistanceLimitConstraintComponent"/>, this constraint allows you to specify
+/// exact attachment points on each body using <see cref="LocalOffsetA"/> and <see cref="LocalOffsetB"/> properties. If you need to
+/// constrain only the centers of bodies, use <see cref="CenterDistanceLimitConstraintComponent"/> instead.
+/// </remarks>
 [DataContract]
 [DefaultEntityComponentProcessor(typeof(ConstraintProcessor), ExecutionMode = ExecutionMode.Runtime)]
 [ComponentCategory("Physics - Bepu Constraint")]
 public sealed class DistanceLimitConstraintComponent : TwoBodyConstraintComponent<DistanceLimit>
 {
     public DistanceLimitConstraintComponent() => BepuConstraint = new() { SpringSettings = new SpringSettings(30, 5) };
 
+    /// <summary>
+    /// Local offset from the center of body A to its attachment point.
+    /// </summary>
     public Vector3 LocalOffsetA
     {
         get
@@ -31,6 +44,9 @@ public Vector3 LocalOffsetA
         }
     }
 
+    /// <summary>
+    /// Local offset from the center of body B to its attachment point.
+    /// </summary>
     public Vector3 LocalOffsetB
     {
         get
@@ -44,6 +60,9 @@ public Vector3 LocalOffsetB
         }
     }
 
+    /// <summary>
+    /// Minimum distance permitted between the point on A and the point on B.
+    /// </summary>
     public float MinimumDistance
     {
         get
@@ -57,6 +76,9 @@ public float MinimumDistance
         }
     }
 
+    /// <summary>
+    /// Maximum distance permitted between the point on A and the point on B.
+    /// </summary>
     public float MaximumDistance
     {
         get

sources/engine/Stride.BepuPhysics/Stride.BepuPhysics/Constraints/DistanceServoConstraintComponent.cs

@@ -2,7 +2,6 @@
 // Distributed under the MIT license. See the LICENSE.md file in the project root for more information.
 
 using BepuPhysics.Constraints;
-using Stride.BepuPhysics.Definitions;
 using Stride.BepuPhysics.Systems;
 using Stride.Core;
 using Stride.Core.Mathematics;
@@ -11,6 +10,18 @@
 
 namespace Stride.BepuPhysics.Constraints;
 
+/// <summary>
+/// Constrains points on two bodies to be separated by a target distance using servo settings.
+/// This constraint attempts to maintain a specific distance between two points on two bodies
+/// by applying forces to reach the target distance. It uses servo settings to control the speed
+/// and force applied to achieve the target distance.
+/// </summary>
+/// <remarks>
+/// Unlike <see cref="CenterDistanceConstraintComponent"/>, this constraint allows you to specify
+/// exact attachment points on each body using <see cref="LocalOffsetA"/> and <see cref="LocalOffsetB"/> properties. If you need to
+/// constrain only the centers of bodies, use <see cref="CenterDistanceConstraintComponent"/> instead.
+/// For a version that allows a range of distances rather than a single target value, see <see cref="DistanceLimitConstraintComponent"/>.
+/// </remarks>
 [DataContract]
 [DefaultEntityComponentProcessor(typeof(ConstraintProcessor), ExecutionMode = ExecutionMode.Runtime)]
 [ComponentCategory("Physics - Bepu Constraint")]
@@ -22,6 +33,9 @@ public sealed class DistanceServoConstraintComponent : TwoBodyConstraintComponen
         ServoSettings = new ServoSettings(10, 1, 1000)
     };
 
+    /// <summary>
+    /// Local offset from the center of body A to its attachment point.
+    /// </summary>
     public Vector3 LocalOffsetA
     {
         get
@@ -35,6 +49,9 @@ public Vector3 LocalOffsetA
         }
     }
 
+    /// <summary>
+    /// Local offset from the center of body B to its attachment point.
+    /// </summary>
     public Vector3 LocalOffsetB
     {
         get
@@ -48,6 +65,9 @@ public Vector3 LocalOffsetB
         }
     }
 
+    /// <summary>
+    /// Distance that the constraint will try to reach between the attachment points.
+    /// </summary>
     public float TargetDistance
     {
         get

sources/engine/Stride.BepuPhysics/Stride.BepuPhysics/Constraints/OneBodyAngularServoConstraintComponent.cs

@@ -2,7 +2,6 @@
 // Distributed under the MIT license. See the LICENSE.md file in the project root for more information.
 
 using BepuPhysics.Constraints;
-using Stride.BepuPhysics.Definitions;
 using Stride.BepuPhysics.Systems;
 using Stride.Core;
 using Stride.Core.Mathematics;
@@ -11,6 +10,19 @@
 
 namespace Stride.BepuPhysics.Constraints;
 
+/// <summary>
+/// Constrains a single body to a target orientation in space, controlling both rotation and tilt.
+/// <para>This constraint applies torque to make a body gradually align with a specific target orientation.
+/// It works like a spring system that pulls the body's orientation (rotation around any axis, including tilt)
+/// toward the specified target orientation.</para>
+/// <para>Common uses include:</para>
+/// <list type="bullet">
+/// <item>Stabilizing objects to maintain a specific orientation</item>
+/// <item>Creating motorized joints that rotate/tilt objects to desired angles</item>
+/// <item>Simulating gyroscopic or magnetic orientation control</item>
+/// </list>
+/// <para>The spring and servo settings control how quickly and forcefully the body moves toward the target orientation.</para>
+/// </summary>
 [DataContract]
 [DefaultEntityComponentProcessor(typeof(ConstraintProcessor), ExecutionMode = ExecutionMode.Runtime)]
 [ComponentCategory("Physics - Bepu Constraint")]