Added comments

Based on discussion #433

Jolt/Physics/Collision/ContactListener.h

@@ -86,12 +86,19 @@ public:
 	/// Called whenever a contact is detected that was also detected last update.
 	/// Note that this callback is called when all bodies are locked, so don't use any locking functions!
 	/// Body 1 and 2 will be sorted such that body 1 ID < body 2 ID, so body 1 may not be dynamic.
+	/// If the structure of the shape of a body changes between simulation steps (e.g. by adding/removing a child shape of a compound shape),
+	/// it is possible that the same sub shape ID used to identify the removed child shape is now reused for a different child shape. The physics
+	/// system cannot detect this, so may send a 'contact persisted' callback even though the contact is now on a different child shape. You can
+	/// detect this by keeping the old shape (before adding/removing a part) around until the next PhysicsSystem::Update (when the OnContactPersisted
+	/// callbacks are triggered) and resolving the sub shape ID against both the old and new shape to see if they still refer to the same child shape.
 	virtual void			OnContactPersisted(const Body &inBody1, const Body &inBody2, const ContactManifold &inManifold, ContactSettings &ioSettings) { /* Do nothing */ }
 
 	/// Called whenever a contact was detected last update but is not detected anymore.
 	/// Note that this callback is called when all bodies are locked, so don't use any locking functions!
 	/// Note that we're using BodyID's since the bodies may have been removed at the time of callback.
 	/// Body 1 and 2 will be sorted such that body 1 ID < body 2 ID, so body 1 may not be dynamic.
+	/// The sub shape ID were created in the previous simulation step too, so if the structure of a shape changes (e.g. by adding/removing a child shape of a compound shape),
+	/// the sub shape ID may not be valid / may not point to the same sub shape anymore.
 	virtual void			OnContactRemoved(const SubShapeIDPair &inSubShapePair) { /* Do nothing */ }
 };
 

Jolt/Physics/Collision/Shape/SubShapeID.h

@@ -5,7 +5,19 @@
 
 JPH_NAMESPACE_BEGIN
 
-/// A sub shape id contains a path to an element (usually a triangle or other primitive type) of a compound shape
+/// @brief A sub shape id contains a path to an element (usually a triangle or other primitive type) of a compound shape
+/// 
+/// Each sub shape knows how many bits it needs to encode its ID, so knows how many bits to take from the sub shape ID.
+/// 
+/// For example:
+/// * We have a CompoundShape A with 5 child shapes (identify sub shape using 3 bits AAA)
+/// * One of its child shapes is CompoundShape B which has 3 child shapes (identify sub shape using 2 bits BB)
+/// * One of its child shapes is MeshShape C which contains enough triangles to need 7 bits to identify a triangle (identify sub shape using 7 bits CCCCCCC, note that MeshShape is block based and sorts triangles spatially, you can't assume that the first triangle will have bit pattern 0000000).
+/// 
+/// The bit pattern of the sub shape ID to identify a triangle in MeshShape C will then be CCCCCCCBBAAA.
+///
+/// A sub shape ID will become invalid when the structure of the shape changes. For example, if a child shape is removed from a compound shape, the sub shape ID will no longer be valid.
+/// This can be a problem when caching sub shape IDs from one frame to the next. See comments at ContactListener::OnContactPersisted / OnContactRemoved.
 class SubShapeID
 {
 public: