Documentation fixes for #150 and #159

Jolt/Physics/Body/MotionProperties.h

@@ -76,6 +76,10 @@ class MotionProperties
 	/// Get inverse mass (1 / mass). Should only be called on a dynamic object (static or kinematic bodies have infinite mass so should be treated as 1 / mass = 0)
 	inline float			GetInverseMass() const											{ JPH_ASSERT(mCachedMotionType == EMotionType::Dynamic); return mInvMass; }
 	inline float			GetInverseMassUnchecked() const									{ return mInvMass; }
+
+	/// Set the inverse mass (1 / mass).
+	/// Note that mass and inertia are linearly related (e.g. inertia of a sphere with mass m and radius r is \f$2/5 \: m \: r^2\f$).
+	/// If you change mass, inertia should probably change as well. See MassProperties::ScaleToMass.
 	void					SetInverseMass(float inInverseMass)								{ mInvMass = inInverseMass; }
 
 	/// Diagonal of inverse inertia matrix: D. Should only be called on a dynamic object (static or kinematic bodies have infinite mass so should be treated as D = 0)
@@ -84,7 +88,9 @@ class MotionProperties
 	/// Rotation (R) that takes inverse inertia diagonal to local space: \f$I_{body}^{-1} = R \: D \: R^{-1}\f$
 	inline Quat		 		GetInertiaRotation() const										{ return mInertiaRotation; }
 
-	/// Set the inverse inertia tensor in local space by setting the diagonal and the rotation: \f$I_{body}^{-1} = R \: D \: R^{-1}\f$
+	/// Set the inverse inertia tensor in local space by setting the diagonal and the rotation: \f$I_{body}^{-1} = R \: D \: R^{-1}\f$.
+	/// Note that mass and inertia are linearly related (e.g. inertia of a sphere with mass m and radius r is \f$2/5 \: m \: r^2\f$).
+	/// If you change inertia, mass should probably change as well. See MassProperties::ScaleToMass.
 	void					SetInverseInertia(Vec3Arg inDiagonal, QuatArg inRot)			{ mInvInertiaDiagonal = inDiagonal; mInertiaRotation = inRot; }
 
 	/// Get inverse inertia matrix (\f$I_{body}^{-1}\f$). Will be a matrix of zeros for a static or kinematic object.

Jolt/Physics/Constraints/DistanceConstraint.h

@@ -35,8 +35,10 @@ class DistanceConstraintSettings final : public TwoBodyConstraintSettings
 	float						mMinDistance = -1.0f;
 	float						mMaxDistance = -1.0f;
 
-	/// If mFrequency != 0 the constraint will be soft and mFrequency specifies the oscillation frequency in Hz and mDamping the damping ratio (0 = no damping, 1 = critical damping).
-	/// Note that due to the way the damping is implemented, it is impossible to get an undamped oscillation. See comment in AxisConstraintPart::CalculateConstraintProperties.
+	/// If mFrequency > 0 the constraint will be soft and mFrequency specifies the oscillation frequency in Hz and mDamping the damping ratio (0 = no damping, 1 = critical damping).
+	/// If mFrequency <= 0, mDamping is ignored and the distance constraint will have hard limits (as hard as the time step / the number of velocity / position solver steps allows).
+	/// Note that if you set mDamping = 0, you will not get an infinite oscillation. Because we integrate physics using an explict Euler scheme, there is always energy loss.
+	/// This is done to keep the simulation from exploding, because with a damping of 0 and even the slightest rounding error, the oscillation could become bigger and bigger until the simluation explodes.
 	float						mFrequency = 0.0f;
 	float						mDamping = 0.0f;
 

Jolt/Physics/Constraints/SliderConstraint.h

@@ -21,7 +21,7 @@ class SliderConstraintSettings final : public TwoBodyConstraintSettings
 	virtual void				SaveBinaryState(StreamOut &inStream) const override;
 
 	/// Create an an instance of this constraint.
-	/// Note that the rotation constraint will be solved from body 1. This means that if body 1 and body 2 have different masses (kinematic body = infinite mass), body 1 should be the heaviest body.
+	/// Note that the rotation constraint will be solved from body 1. This means that if body 1 and body 2 have different masses / inertias (kinematic body = infinite mass / inertia), body 1 should be the heaviest body.
 	virtual TwoBodyConstraint *	Create(Body &inBody1, Body &inBody2) const override;
 
 	/// Simple way of setting the anchor points in world space so that the current relative position is chosen as the '0' position