Added some notes in function documentation

src/object/interface/damageable_object.h

@@ -48,6 +48,7 @@ public:
     virtual ~CDamageableObject()
     {}
 
-    //! Damage the object, with the given force. Returns true if the object has been fully destroyed (if the object is destroyable). force < 0 => destroy immediately (default), force == 0 => default damage values
+    //! Damage the object, with the given force. Returns true if the object has been fully destroyed (assuming the object is destroyable, of course). force < 0 => destroy immediately (default), force == 0 => default damage values
+    // NOTE: You should never assume that after this function exits, the object is destroyed, unless it returns true. Even if you specify force = -1, if may still sometimes decide not to destroy the object.
     virtual bool DamageObject(DamageType type, float force = -1.0f) = 0;
 };

src/object/interface/destroyable_object.h

@@ -48,8 +48,9 @@ public:
     {}
 
     //! Destroy the object immediately. Use this only if you are 100% sure this is what you want, because object with magnifyDamage=0 should be able to bypass all damage. It's recommended to use CDamageableObject::DamageObject() instead.
+    // NOTE: After this function exits, you can assume the object has been definetly destroyed
     virtual void DestroyObject(DestructionType type) = 0;
 
-    //! Returns the distance modifier for lightning, used to modify hit probability. Value in range [0..1], where 0 is never and 1 is normal probability
+    //! Returns the distance modifier for CLightning, used to modify hit probability. Value in range [0..1], where 0 is never and 1 is normal probability
     virtual float GetLightningHitProbability() = 0;
 };