Finished remaining physics documentation

BansheeCore/Include/BsBoxCollider.h

@@ -9,15 +9,32 @@
 
 namespace BansheeEngine
 {
+	/** @addtogroup Physics
+	 *  @{
+	 */
+
+	/** Collider with a box geometry. */
 	class BS_CORE_EXPORT BoxCollider : public Collider
 	{
 	public:
 		BoxCollider();
 
+		/** Sets the extents of the geometry of the box. Extents are size/2. */
 		virtual void setExtents(const Vector3& extents) = 0;
+
+		/** Gets the extents of the geometry of the box. Extents are size/2. */
 		virtual Vector3 getExtents() const = 0;
 
+		/** 
+		 * Creates a new box collider. 
+		 *
+		 * @param[in]	extents		Extents of the box. Extents are size/2.
+		 * @param[in]	position	Center of the box.
+		 * @param[in]	rotation	Rotation of the box.
+		 */
 		static SPtr<BoxCollider> create(const Vector3& extents = Vector3::ZERO, 
 			const Vector3& position = Vector3::ZERO, const Quaternion& rotation = Quaternion::IDENTITY);
 	};
+
+	/** @} */
 }

BansheeCore/Include/BsCapsuleCollider.h

@@ -9,15 +9,26 @@
 
 namespace BansheeEngine
 {
+	/** @addtogroup Physics
+	 *  @{
+	 */
+
+	 /** Collider with a capsule geometry. */
 	class BS_CORE_EXPORT CapsuleCollider : public Collider
 	{
 	public:
 		CapsuleCollider();
 
-		/** Sets the height of the capsule, from the origin to one of the hemispherical centers, along the normal vector. */
+		/** 
+		 * Sets the half height of the capsule, from the origin to one of the hemispherical centers, along the normal 
+		 * vector. 
+		 */
 		virtual void setHalfHeight(float halfHeight) = 0;
 
-		/** Gets the height of the capsule, from the origin to one of the hemispherical centers, along the normal vector. */
+		/** 
+		 * Gets the half  height of the capsule, from the origin to one of the hemispherical centers, along the normal
+		 * vector. 
+		 */
 		virtual float getHalfHeight() const = 0;
 
 		/** Sets the radius of the capsule. */
@@ -26,7 +37,18 @@ namespace BansheeEngine
 		/** Gets the radius of the capsule. */
 		virtual float getRadius() const = 0;
 
+		/** 
+		 * Creates a new capsule collider. 
+		 *
+		 * @param[in]	radius		Radius of the capsule.
+		 * @param[in]	halfHeight	Half height of the capsule, from the origin to one of the hemispherical centers, along
+		 *							the normal vector.
+		 * @param[in]	position	Center of the box.
+		 * @param[in]	rotation	Rotation of the box.
+		 */
 		static SPtr<CapsuleCollider> create(float radius = 0.0f, float halfHeight = 0.0f, 
 			const Vector3& position = Vector3::ZERO, const Quaternion& rotation = Quaternion::IDENTITY);
 	};
+
+	/** @} */
 }

BansheeCore/Include/BsCollider.h

@@ -9,37 +9,77 @@
 
 namespace BansheeEngine
 {
+	/** @addtogroup Physics
+	 *  @{
+	 */
+
+	/** 
+	 * Collider represents physics geometry that can be in multiple states:
+	 *  - Default: Static geometry that physics objects can collide with.
+	 *  - Trigger: Static geometry that can't be collided with but will report touch events.
+	 *  - Dynamic: Dynamic geometry that is a part of a Rigidbody. A set of colliders defines the shape of the parent 
+	 *		       rigidbody.
+	 */
 	class BS_CORE_EXPORT Collider
 	{
 	public:
 		virtual ~Collider() { }
 
+		/** @copydoc FCollider::getPosition */
 		inline Vector3 getPosition() const;
+
+		/** @copydoc FCollider::getRotation */
 		inline Quaternion getRotation() const;
+
+		/** @copydoc FCollider::setTransform */
 		inline void setTransform(const Vector3& pos, const Quaternion& rot);
 
+		/** @copydoc FCollider::setScale */
 		virtual void setScale(const Vector3& scale);
+
+		/** @copydoc FCollider::getScale */
 		inline Vector3 getScale() const;
 
+		/** @copydoc FCollider::setIsTrigger */
 		inline void setIsTrigger(bool value);
+
+		/** @copydoc FCollider::getIsTrigger */
 		inline bool getIsTrigger() const;
 
+		/** @copydoc FCollider::setRigidbody */
 		inline void setRigidbody(Rigidbody* value);
+
+		/** @copydoc FCollider::getRigidbody */
 		Rigidbody* getRigidbody() const { return mRigidbody; }
 
+		/** @copydoc FCollider::setMass */
 		inline void setMass(float mass);
+
+		/** @copydoc FCollider::getMass */
 		inline float getMass() const;
 
+		/** @copydoc FCollider::setMaterial */
 		inline void setMaterial(const HPhysicsMaterial& material);
+
+		/** @copydoc FCollider::getMaterial */
 		inline HPhysicsMaterial getMaterial() const;
 
+		/** @copydoc FCollider::setContactOffset */
 		inline void setContactOffset(float value);
+
+		/** @copydoc FCollider::getContactOffset */
 		inline float getContactOffset();
 
+		/** @copydoc FCollider::setRestOffset */
 		inline void setRestOffset(float value);
+
+		/** @copydoc FCollider::getRestOffset */
 		inline float getRestOffset();
 
+		/** @copydoc FCollider::setLayer */
 		inline void setLayer(UINT64 layer);
+
+		/** @copydoc FCollider::getLayer */
 		inline UINT64 getLayer() const;
 
 		/** Sets a value that determines which (if any) collision events are reported. */
@@ -70,12 +110,25 @@ namespace BansheeEngine
 		inline bool rayCast(const Vector3& origin, const Vector3& unitDir, PhysicsQueryHit& hit,
 			float maxDist = FLT_MAX) const;
 
+		/** 
+		 * Triggered when some object starts interacting with the collider. Only triggered if proper collision report mode
+		 * is turned on. 
+		 */
 		Event<void(const CollisionData&)> onCollisionBegin;
+		/** 
+		 * Triggered for every frame that an object remains interacting with a collider. Only triggered if proper collision
+		 * report mode is turned on. 
+		 */
 		Event<void(const CollisionData&)> onCollisionStay;
+		/**
+		 * Triggered when some object stops interacting with the collider. Only triggered if proper collision report mode
+		 * is turned on. 
+		 */
 		Event<void(const CollisionData&)> onCollisionEnd;
 
 		/** @cond INTERNAL */
 
+		/** Returns the object containing common collider code. */
 		FCollider* _getInternal() const { return mInternal; }
 
 		/** 
@@ -97,4 +150,6 @@ namespace BansheeEngine
 		Rigidbody* mRigidbody = nullptr;
 		Vector3 mScale = Vector3::ONE;
 	};
+
+	/** @} */
 }

BansheeCore/Include/BsFCollider.h

@@ -9,26 +9,58 @@
 
 namespace BansheeEngine
 {
+	/** @cond INTERNAL */
+	/** @addtogroup Physics
+	 *  @{
+	 */
+
+	/** Provides common functionality used by all Collider types. */
 	class BS_CORE_EXPORT FCollider
 	{
 	public:
 		virtual ~FCollider();
 
+		/** Returns the position of the collider. */
 		virtual Vector3 getPosition() const = 0;
+
+		/** Returns the rotation of the collider. */
 		virtual Quaternion getRotation() const = 0;
+
+		/** Sets the position and rotation of the collider. */
 		virtual void setTransform(const Vector3& pos, const Quaternion& rotation) = 0;
 
+		/** 
+		 * Enables/disables a collider as a trigger. A trigger will not be used for collisions (i.e. objects will pass 
+		 * through it), but collision events will still be reported. 
+		 */
 		virtual void setIsTrigger(bool value) = 0;
+
+		/** Checks is the collider a trigger. */
 		virtual bool getIsTrigger() const = 0;
 
+		/** 
+		 * Changes whether the collider is a part of a rigidbody (non-static), or is on its own (static). You should change
+		 * this whenever you are attaching or detaching a collider from a rigidbody.
+		 */
 		virtual void setIsStatic(bool value) = 0;
+
+		/** Checks whether the collider is a part of a rigidbody (non-static), or is on its own (static). */
 		virtual bool getIsStatic() const = 0;
 
-		// Not used for triggers, only relevant if parent rigidbody uses child mass
+		/** 
+		 * Sets the mass of the collider. Only relevant if the collider is part of a rigidbody. Ultimately this will
+		 * determine the total mass, center of mass and inertia tensors of the parent rigidbody (if they're being calculated
+		 * automatically).
+		 */
 		virtual void setMass(float mass) { mMass = mass; }
+
+		/** Returns the mass of the collider. */
 		virtual float getMass() const { return mMass; }
 
+		/** Sets the material of the collider. The material determines how objects hitting the collider behave. */
 		virtual void setMaterial(const HPhysicsMaterial& material);
+
+		/** Gets the material of the collider. The material determines how objects hitting the collider behave. */
 		virtual HPhysicsMaterial getMaterial() const { return mMaterial; }
 
 		/**
@@ -53,10 +85,16 @@ namespace BansheeEngine
 		/** Returns shepe's rest offset in meters. See setRestOffset() to learn what contact offset is. */
 		virtual float getRestOffset() const = 0;
 
+		/** Sets the layer of the collider. Layer controls with which objects will the collider collide. */
 		virtual void setLayer(UINT64 layer) = 0;
+
+		/** Gets the layer of the collider. Layer controls with which objects will the collider collide. */
 		virtual UINT64 getLayer() const = 0;
 
+		/** Sets a value that determines which (if any) collision events are reported. */
 		virtual void setCollisionReportMode(CollisionReportMode mode) = 0;
+
+		/** Gets a value that determines which (if any) collision events are reported. */
 		virtual CollisionReportMode getCollisionReportMode() const = 0;
 
 		/** Enables continous collision detect for this collider. Only valid if the collider is a part of a rigidbody. */
@@ -66,4 +104,7 @@ namespace BansheeEngine
 		
 		HPhysicsMaterial mMaterial;
 	};
+
+	/** @} */
+	/** @endcond */
 }

BansheeCore/Include/BsMeshCollider.h

@@ -8,14 +8,33 @@
 
 namespace BansheeEngine
 {
+	/** @addtogroup Physics
+	 *  @{
+	 */
+
+	/** A collider represented by an arbitrary mesh. */
 	class BS_CORE_EXPORT MeshCollider : public Collider, public IResourceListener
 	{
 	public:
 		MeshCollider();
 
+		/** 
+		 * Sets a mesh that represents the collider geometry. 
+		 *
+		 * @param[in]	mesh	Generic triangle mesh, or and convex mesh. Triangle meshes are not supported as triggers, 
+		 *						nor are they supported for colliders that are parts of a non-kinematic rigidbody.
+		 */
 		void setMesh(const HPhysicsMesh& mesh) { mMesh = mesh; onMeshChanged();  markListenerResourcesDirty(); }
+
+		/** Returns a mesh that represents the collider geometry. */
 		HPhysicsMesh getMesh() const { return mMesh; }
 
+		/** 
+		 * Creates a new mesh collider. 
+		 *
+		 * @param[in]	position	Position of the collider.
+		 * @param[in]	rotation	Rotation of the collider.
+		 */
 		static SPtr<MeshCollider> create(const Vector3& position = Vector3::ZERO, 
 			const Quaternion& rotation = Quaternion::IDENTITY);
 
@@ -33,4 +52,6 @@ namespace BansheeEngine
 
 		HPhysicsMesh mMesh;
 	};
+
+	/** @} */
 }

BansheeCore/Include/BsPhysics.h

@@ -11,6 +11,10 @@
 
 namespace BansheeEngine
 {
+	/** @addtogroup Physics
+	 *  @{
+	 */
+
 	struct PHYSICS_INIT_DESC;
 
 	/** Flags for controlling physics behaviour globally. */
@@ -47,41 +51,13 @@ namespace BansheeEngine
 	typedef Flags<PhysicsFlag> PhysicsFlags;
 	BS_FLAGS_OPERATORS(PhysicsFlag)
 
+	/** Provides global physics settings, factory methods for physics objects and scene queries. */
 	class BS_CORE_EXPORT Physics : public Module<Physics>
 	{
 	public:
 		Physics(const PHYSICS_INIT_DESC& init);
 		virtual ~Physics() { }
 
-		virtual void update() = 0;
-
-		/******************************************************************************************************************/
-		/************************************************* CREATION *******************************************************/
-		/******************************************************************************************************************/
-
-		virtual SPtr<PhysicsMaterial> createMaterial(float staticFriction, float dynamicFriction, float restitution) = 0;
-		virtual SPtr<PhysicsMesh> createMesh(const MeshDataPtr& meshData, PhysicsMeshType type) = 0;
-		virtual SPtr<Rigidbody> createRigidbody(const HSceneObject& linkedSO) = 0;
-
-		virtual SPtr<BoxCollider> createBoxCollider(const Vector3& extents, const Vector3& position, 
-			const Quaternion& rotation) = 0;
-		virtual SPtr<SphereCollider> createSphereCollider(float radius,
-			const Vector3& position, const Quaternion& rotation) = 0;
-		virtual SPtr<PlaneCollider> createPlaneCollider(const Vector3& position, const Quaternion& rotation) = 0;
-		virtual SPtr<CapsuleCollider> createCapsuleCollider(float radius, float halfHeight,
-			const Vector3& position, const Quaternion& rotation) = 0;
-		virtual SPtr<MeshCollider> createMeshCollider(const Vector3& position, const Quaternion& rotation) = 0;
-
-		virtual SPtr<FixedJoint> createFixedJoint() = 0;
-		virtual SPtr<DistanceJoint> createDistanceJoint() = 0;
-		virtual SPtr<HingeJoint> createHingeJoint() = 0;
-		virtual SPtr<SphericalJoint> createSphericalJoint() = 0;
-		virtual SPtr<SliderJoint> createSliderJoint() = 0;
-		virtual SPtr<D6Joint> createD6Joint() = 0;
-
-		/** @copydoc CharacterController::create */
-		virtual SPtr<CharacterController> createCharacterController(const CHAR_CONTROLLER_DESC& desc) = 0;
-
 		/******************************************************************************************************************/
 		/************************************************* QUERIES ********************************************************/
 		/******************************************************************************************************************/
@@ -427,14 +403,29 @@ namespace BansheeEngine
 		/************************************************* OPTIONS ********************************************************/
 		/******************************************************************************************************************/
 
+		/** Checks is a specific physics option enabled. */
 		virtual bool hasFlag(PhysicsFlags flag) const { return mFlags & flag; }
+
+		/** Enables or disabled a specific physics option. */
 		virtual void setFlag(PhysicsFlags flag, bool enabled) { if (enabled) mFlags |= flag; else mFlags &= ~flag; }
 
+		/** Gets the global gravity value for all objects in the scene. */
 		virtual Vector3 getGravity() const = 0;
+
+		/** Sets the global gravity value for all objects in the scene. */
 		virtual void setGravity(const Vector3& gravity) = 0;
 
+		/** 
+		 * Adds a new physics region. Certain physics options require you to set up regions in which physics objects are
+		 * allowed to be in, and objects outside of these regions will not be handled by physics. You do not need to set
+		 * up these regions by default.
+		 */
 		virtual UINT32 addBroadPhaseRegion(const AABox& region) = 0;
+
+		/** Removes a physics region. */
 		virtual void removeBroadPhaseRegion(UINT32 handle) = 0;
+
+		/** Removes all physics regions. */
 		virtual void clearBroadPhaseRegions() = 0;
 
 		/** 
@@ -451,11 +442,72 @@ namespace BansheeEngine
 		 */
 		virtual void setMaxTesselationEdgeLength(float length) = 0;
 
+		/** 
+		 * Enables or disables collision between two layers. Each physics object can be assigned a specific layer, and here
+		 * you can determine which layers can interact with each other.
+		 */
 		void toggleCollision(UINT64 groupA, UINT64 groupB, bool enabled);
+
+		/** Checks if two collision layers are allowed to interact. */
 		bool isCollisionEnabled(UINT64 groupA, UINT64 groupB) const;
 
 		/** @cond INTERNAL */
 
+		/******************************************************************************************************************/
+		/************************************************* CREATION *******************************************************/
+		/******************************************************************************************************************/
+
+		/** @copydoc PhysicsMaterial::create */
+		virtual SPtr<PhysicsMaterial> createMaterial(float staticFriction, float dynamicFriction, float restitution) = 0;
+
+		/** @copydoc PhysicsMesh::create */
+		virtual SPtr<PhysicsMesh> createMesh(const MeshDataPtr& meshData, PhysicsMeshType type) = 0;
+
+		/** @copydoc Rigidbody::create */
+		virtual SPtr<Rigidbody> createRigidbody(const HSceneObject& linkedSO) = 0;
+
+		/** @copydoc BoxCollider::create */
+		virtual SPtr<BoxCollider> createBoxCollider(const Vector3& extents, const Vector3& position,
+			const Quaternion& rotation) = 0;
+
+		/** @copydoc SphereCollider::create */
+		virtual SPtr<SphereCollider> createSphereCollider(float radius,
+			const Vector3& position, const Quaternion& rotation) = 0;
+
+		/** @copydoc PlaneCollider::create */
+		virtual SPtr<PlaneCollider> createPlaneCollider(const Vector3& position, const Quaternion& rotation) = 0;
+
+		/** @copydoc CapsuleCollider::create */
+		virtual SPtr<CapsuleCollider> createCapsuleCollider(float radius, float halfHeight,
+			const Vector3& position, const Quaternion& rotation) = 0;
+
+		/** @copydoc MeshCollider::create */
+		virtual SPtr<MeshCollider> createMeshCollider(const Vector3& position, const Quaternion& rotation) = 0;
+
+		/** @copydoc FixedJoint::create */
+		virtual SPtr<FixedJoint> createFixedJoint() = 0;
+
+		/** @copydoc DistanceJoint::create */
+		virtual SPtr<DistanceJoint> createDistanceJoint() = 0;
+
+		/** @copydoc HingeJoint::create */
+		virtual SPtr<HingeJoint> createHingeJoint() = 0;
+
+		/** @copydoc SphericalJoint::create */
+		virtual SPtr<SphericalJoint> createSphericalJoint() = 0;
+
+		/** @copydoc SliderJoint::create */
+		virtual SPtr<SliderJoint> createSliderJoint() = 0;
+
+		/** @copydoc D6Joint::create */
+		virtual SPtr<D6Joint> createD6Joint() = 0;
+
+		/** @copydoc CharacterController::create */
+		virtual SPtr<CharacterController> createCharacterController(const CHAR_CONTROLLER_DESC& desc) = 0;
+
+		/** Triggers physics simulation update as needed. Should be called once per frame. */
+		virtual void update() = 0;
+
 		/** @copydoc Physics::boxOverlap() */
 		virtual Vector<Collider*> _boxOverlap(const AABox& box, const Quaternion& rotation,
 			UINT64 layer = BS_ALL_LAYERS) const = 0;
@@ -484,6 +536,7 @@ namespace BansheeEngine
 		virtual bool _rayCast(const Vector3& origin, const Vector3& unitDir, const Collider& collider, PhysicsQueryHit& hit, 
 			float maxDist = FLT_MAX) const = 0;
 
+		/** Checks is the physics update currently in progress. */
 		bool _isUpdateInProgress() const { return mUpdateInProgress; }
 
 		/** @endcond */
@@ -492,8 +545,24 @@ namespace BansheeEngine
 	protected:
 		friend class Rigidbody;
 
+		/** 
+		 * Registers a new rigidbody. Should be called whenever a new rigidbody is created. 
+		 * 
+		 * @param[in]	body		Newly created rigidbody.
+		 * @param[in]	priority	Priority that determines in what order is the physics simulation update applied to
+		 *							rigidbodes. Higher priority means it is applied before lower priority.
+		 */
 		void registerRigidbody(Rigidbody* body, UINT32 priority);
+
+		/** 
+		 * Unregisters a rigidbody. Should be called before a rigidbody is destroyed.
+		 *
+		 * @param[in]	id			ID of the rigidbody to remove.
+		 * @param[in]	priority	Original priority of the rigidbody.
+		 */
 		void unregisterRigidbody(UINT32 id, UINT32 priority);
+
+		/** Changes the priority of a rigidbody. */
 		void updatePriority(UINT32 id, UINT32 oldPriority, UINT32 newPriority);
 
 		mutable Mutex mMutex;
@@ -509,13 +578,17 @@ namespace BansheeEngine
 	/** Provides easier access to Physics. */
 	BS_CORE_EXPORT Physics& gPhysics();
 
+	/** Contains parameters used for initializing the physics system. */
 	struct PHYSICS_INIT_DESC
 	{
-		float typicalLength = 1.0f;
-		float typicalSpeed = 9.81f;
-		Vector3 gravity = Vector3(0.0f, -9.81f, 0.0f);
-		bool initCooking = true; // TODO: Disable this for Game build
-		float timeStep = 1.0f / 60.0f;
+		float typicalLength = 1.0f; /**< Typical length of an object in the scene. */
+		float typicalSpeed = 9.81f; /**< Typical speed of an object in the scene. */
+		Vector3 gravity = Vector3(0.0f, -9.81f, 0.0f); /**< Initial gravity. */
+		bool initCooking = true; /**< Determines should the cooking library be initialized. */
+		float timeStep = 1.0f / 60.0f; /**< Determines using what interval should the physics update happen. */
+		/** Flags that control global physics option. */
 		PhysicsFlags flags = PhysicsFlag::CCT_OverlapRecovery | PhysicsFlag::CCT_PreciseSweeps | PhysicsFlag::CCD_Enable;
 	};
+
+	/** @} */
 }

BansheeCore/Include/BsPhysicsCommon.h

@@ -8,6 +8,10 @@
 
 namespace BansheeEngine
 {
+	/** @addtogroup Physics
+	 *  @{
+	 */
+
 	/** Information about a single contact point during physics collision. */
 	struct ContactPoint
 	{
@@ -74,4 +78,6 @@ namespace BansheeEngine
 		 */
 		HCollider collider;
 	};
+
+	/** @} */
 }

BansheeCore/Include/BsPhysicsManager.h

@@ -7,18 +7,35 @@
 
 namespace BansheeEngine
 {
+	/** @cond INTERNAL */
+	/** @addtogroup Physics
+	 *  @{
+	 */
+
+	/** Creates and destroys a specific physics implementation. */
 	class BS_CORE_EXPORT PhysicsFactory
 	{
 	public:
 		virtual ~PhysicsFactory() { }
 
+		/** Initializes the physics system. */
 		virtual void startUp(bool cooking) = 0;
+
+		/** Shuts down the physics system. */
 		virtual void shutDown() = 0;
 	};
 
+	/** Takes care of loading, initializing and shutting down of a particular physics implementation. */
 	class BS_CORE_EXPORT PhysicsManager : public Module<PhysicsManager>
 	{
 	public:
+		/** 
+		 * Initializes the physics manager and a particular physics implementation. 
+		 *
+		 * @param[in]	pluginName	Name of the plugin containing a physics implementation.
+		 * @param[in]	cookign		Should the cooking library be initialized with physics (normally only needed for 
+		 *							editor).
+		 */
 		PhysicsManager(const String& pluginName, bool cooking);
 		~PhysicsManager();
 
@@ -26,4 +43,7 @@ namespace BansheeEngine
 		DynLib* mPlugin;
 		PhysicsFactory* mFactory;
 	};
+
+	/** @} */
+	/** @endcond */
 }

BansheeCore/Include/BsPhysicsMaterial.h

@@ -7,22 +7,70 @@
 
 namespace BansheeEngine
 {
+	/** @addtogroup Physics
+	 *  @{
+	 */
+
+	/** Physics material that controls how objects react when they collide. */
 	class BS_CORE_EXPORT PhysicsMaterial : public Resource
 	{
 	public:
 		virtual ~PhysicsMaterial() { }
 
+		/** 
+		  * Sets static friction of the material. Controls friction when two in-contact objects are not moving lateral to
+		  * each other (e.g. how difficult is to get an object moving from a static state while it is in contact other
+		  * object(s)).
+		  */
 		virtual void setStaticFriction(float value) = 0;
+
+		/** Gets static friction of the material. */
 		virtual float getStaticFriction() const = 0;
 
+		/**
+		 * Sets dynamic friction of the material. Controls friction when two in-contact objects are moving lateral to each
+		 * other (e.g. how quickly does an object slow down when sliding along another object).
+		 */
 		virtual void setDynamicFriction(float value) = 0;
+
+		/** Gets dynamic friction of the material .*/
 		virtual float getDynamicFriction() const = 0;
 
+		/** 
+		 * Sets restitution coefficient of the material. Controls "bounciness" of an object during a collision. Value of 1
+		 * means the collision is elastic, and value of 0 means the value is inelastic. Must be in [0, 1] range.
+		 */
 		virtual void setRestitutionCoefficient(float value) = 0;
+
+		/** Gets restitution coefficient of the material. */
 		virtual float getRestitutionCoefficient() const = 0;
 
+		/** 
+		 * Creates a new physics material. 
+		 *
+		 * @param[in]	staticFriction	Controls friction when two in-contact objects are not moving lateral to each other
+		 *								(e.g. how difficult is to get an object moving from a static state while it is in
+		 *								contact other object(s)).
+		 * @param[in]	dynamicFriction	Sets dynamic friction of the material. Controls friction when two in-contact objects
+		 *								are moving lateral to each other (e.g. how quickly does an object slow down when
+		 *								sliding along another object).
+		 * @param[in]	restitution		Controls "bounciness" of an object during a collision. Value of 1 means the
+		 *								collision is elastic, and value of 0 means the value is inelastic. Must be in
+		 *								[0, 1] range.
+		 */
 		static HPhysicsMaterial create(float staticFriction = 0.0f, float dynamicFriction = 0.0f, float restitution = 0.0f);
-		static PhysicsMaterialPtr _createPtr(float staticFriction = 0.0f, float dynamicFriction = 0.0f, float restitution = 0.0f);
+
+		/** @cond INTERNAL */
+
+		/** 
+		 * @copydoc create()
+		 *
+		 * For internal use. Requires manual initialization after creation.
+		 */
+		static PhysicsMaterialPtr _createPtr(float staticFriction = 0.0f, float dynamicFriction = 0.0f, 
+			float restitution = 0.0f);
+
+		/** @endcond */
 
 		/************************************************************************/
 		/* 								SERIALIZATION                      		*/
@@ -32,4 +80,6 @@ namespace BansheeEngine
 		static RTTITypeBase* getRTTIStatic();
 		RTTITypeBase* getRTTI() const override;
 	};
+
+	/** @} */
 }

BansheeCore/Include/BsPhysicsMesh.h

@@ -7,20 +7,48 @@
 
 namespace BansheeEngine
 {
+	/** @addtogroup Physics
+	 *  @{
+	 */
+
+	/** 
+	 * Represents a physics mesh that can be used for physics MeshCollider%s. Physics mesh can be a generic triangle mesh
+	 * or a convex mesh. Convex meshes are limited to 255 faces.
+	 */
 	class BS_CORE_EXPORT PhysicsMesh : public Resource
 	{
 	public:
 		PhysicsMesh(const MeshDataPtr& meshData, PhysicsMeshType type);
 		virtual ~PhysicsMesh() { }
 
+		/** Returns the type of the physics mesh. */
 		PhysicsMeshType getType() const { return mType; }
+
+		/** Returns the mesh's indices and vertices. */
 		virtual MeshDataPtr getMeshData() const = 0;
 
+		/** 
+		 * Creates a new physics mesh. 
+		 *
+		 * @param[in]	meshData	Index and vertices of the mesh data.
+		 * @param[in]	type		Type of the mesh. If convex the provided mesh geometry will be converted into a convex
+		 *							mesh (that might not be the same as the provided mesh data).
+		 */
 		static HPhysicsMesh create(const MeshDataPtr& meshData, PhysicsMeshType type = PhysicsMeshType::Convex);
+
+		/** @cond INTERNAL */
+
+		/** 
+		 * @copydoc create()
+		 *
+		 * For internal use. Requires manual initialization after creation.
+		 */
 		static PhysicsMeshPtr _createPtr(const MeshDataPtr& meshData, PhysicsMeshType type);
 
+		/** @endcond */
+
 	protected:
-		/** @copydoc PhysicsMesh::initialize() */
+		/** @copydoc Resource::initialize() */
 		void initialize() override;
 
 		PhysicsMeshType mType;
@@ -35,4 +63,6 @@ namespace BansheeEngine
 		static RTTITypeBase* getRTTIStatic();
 		RTTITypeBase* getRTTI() const override;
 	};
+
+	/** @} */
 }

BansheeCore/Include/BsPlaneCollider.h

@@ -9,12 +9,25 @@
 
 namespace BansheeEngine
 {
+	/** @addtogroup Physics
+	 *  @{
+	 */
+
+	/** A collider with plane geometry. Plane colliders cannot be a part of non-kinematic rigidbodies. */
 	class BS_CORE_EXPORT PlaneCollider : public Collider
 	{
 	public:
 		PlaneCollider();
 
+		/** 
+		 * Creates a new plane collider. 
+		 *
+		 * @param[in]	position	Position of the collider.
+		 * @param[in]	rotation	Rotation of the collider.
+		 */
 		static SPtr<PlaneCollider> create(const Vector3& position = Vector3::ZERO, 
 			const Quaternion& rotation = Quaternion::IDENTITY);
 	};
+
+	/** @} */
 }

BansheeCore/Include/BsRigidbody.h

@@ -7,6 +7,10 @@
 
 namespace BansheeEngine
 {
+	/** @addtogroup Physics
+	 *  @{
+	 */
+
 	/** Type of force or torque that can be applied to a rigidbody. */
 	enum class ForceMode
 	{
@@ -23,10 +27,6 @@ namespace BansheeEngine
 		Impulse, /**< Value applied is an impulse (i.e. a direct change in its linear or angular momentum). */
 	};
 
-	/** @addtogroup Physics
-	 *  @{
-	 */
-
 	/**
 	 * Rigidbody is a dynamic physics object that can be moved using forces (or directly). It will interact with other
 	 * static and dynamic physics objects in the scene accordingly (i.e. it will push other non-kinematic rigidbodies, 

BansheeCore/Include/BsSphereCollider.h

@@ -9,15 +9,32 @@
 
 namespace BansheeEngine
 {
+	/** @addtogroup Physics
+	 *  @{
+	 */
+
+	/** A collider with sphere geometry. */
 	class BS_CORE_EXPORT SphereCollider : public Collider
 	{
 	public:
 		SphereCollider();
 
+		/** Sets the radius of the sphere geometry. */
 		virtual void setRadius(float radius) = 0;
+
+		/** Gets the radius of the sphere geometry. */
 		virtual float getRadius() const = 0;
 
+		/**
+		 * Creates a new sphere collider.
+		 * 
+		 * @param[in]	radius		Radius of the sphere geometry.
+		 * @param[in]	position	Position of the collider.
+		 * @param[in]	rotation	Rotation of the collider.
+		 */
 		static SPtr<SphereCollider> create(float radius = 0.0f, const Vector3& position = Vector3::ZERO, 
 			const Quaternion& rotation = Quaternion::IDENTITY);
 	};
+
+	/** @} */
 }

BansheePhysX/Include/BsPhysX.h

@@ -12,8 +12,14 @@
 
 namespace BansheeEngine
 {
+	/** @addtogroup PhysX
+	 *  @{
+	 */
+
+	/** NVIDIA PhysX implementation of Physics. */
 	class PhysX : public Physics
 	{
+		/** Type of contacts reported by PhysX simulation. */
 		enum class ContactEventType
 		{
 			ContactBegin,
@@ -21,49 +27,79 @@ namespace BansheeEngine
 			ContactEnd
 		};
 
+		/** Event reported when a physics object interacts with a collider. */
 		struct TriggerEvent
 		{
-			Collider* trigger;
-			Collider* other;
-			ContactEventType type;
+			Collider* trigger; /** Trigger that was interacted with. */
+			Collider* other; /** Collider that was interacted with. */
+			ContactEventType type; /** Exact type of the event. */
 		};
 
+		/** Event reported when two colliders interact. */
 		struct ContactEvent
 		{
-			Collider* colliderA;
-			Collider* colliderB;
-			ContactEventType type;
-			Vector<ContactPoint> points; // Note: Not too happy this is heap allocated, use static allocator?
+			Collider* colliderA; /** First collider. */
+			Collider* colliderB; /** Second collider. */
+			ContactEventType type; /** Exact type of the event. */
+			// Note: Not too happy this is heap allocated, use static allocator?
+			Vector<ContactPoint> points; /** Information about all contact points between the colliders. */
 		};
 
+		/** Event reported when a joint breaks. */
 		struct JointBreakEvent
 		{
-			Joint* joint;
+			Joint* joint; /** Broken joint. */
 		};
 
 	public:
 		PhysX(const PHYSICS_INIT_DESC& input);
 		~PhysX();
 
+		/** @copydoc Physics::update */
 		void update() override;
 
+		/** @copydoc Physics::createMaterial */
 		SPtr<PhysicsMaterial> createMaterial(float staticFriction, float dynamicFriction, float restitution) override;
+
+		/** @copydoc Physics::createMesh */
 		SPtr<PhysicsMesh> createMesh(const MeshDataPtr& meshData, PhysicsMeshType type) override;
+
+		/** @copydoc Physics::createRigidbody */
 		SPtr<Rigidbody> createRigidbody(const HSceneObject& linkedSO) override;
 
+		/** @copydoc Physics::createBoxCollider */
 		SPtr<BoxCollider> createBoxCollider(const Vector3& extents, const Vector3& position,
 			const Quaternion& rotation) override;
+
+		/** @copydoc Physics::createSphereCollider */
 		SPtr<SphereCollider> createSphereCollider(float radius, const Vector3& position, const Quaternion& rotation) override;
+
+		/** @copydoc Physics::createPlaneCollider */
 		SPtr<PlaneCollider> createPlaneCollider(const Vector3& position, const Quaternion& rotation) override;
+
+		/** @copydoc Physics::createCapsuleCollider */
 		SPtr<CapsuleCollider> createCapsuleCollider(float radius, float halfHeight, const Vector3& position, 
 			const Quaternion& rotation) override;
+
+		/** @copydoc Physics::createMeshCollider */
 		SPtr<MeshCollider> createMeshCollider(const Vector3& position, const Quaternion& rotation) override;
 
+		/** @copydoc Physics::createFixedJoint */
 		SPtr<FixedJoint> createFixedJoint() override;
+
+		/** @copydoc Physics::createDistanceJoint */
 		SPtr<DistanceJoint> createDistanceJoint() override;
+
+		/** @copydoc Physics::createHingeJoint */
 		SPtr<HingeJoint> createHingeJoint() override;
+
+		/** @copydoc Physics::createSphericalJoint */
 		SPtr<SphericalJoint> createSphericalJoint() override;
+
+		/** @copydoc Physics::createSliderJoint */
 		SPtr<SliderJoint> createSliderJoint() override;
+
+		/** @copydoc Physics::createD6Joint */
 		SPtr<D6Joint> createD6Joint() override;
 
 		/** @copydoc Physics::createCharacterController*/
@@ -144,16 +180,28 @@ namespace BansheeEngine
 		bool convexOverlapAny(const HPhysicsMesh& mesh, const Vector3& position, const Quaternion& rotation,
 			UINT64 layer = BS_ALL_LAYERS) const override;
 
+		/** @copydoc Physics::setFlag */
 		void setFlag(PhysicsFlags flags, bool enabled) override;
 
+		/** @copydoc Physics::getGravity */
 		Vector3 getGravity() const override;
+
+		/** @copydoc Physics::setGravity */
 		void setGravity(const Vector3& gravity) override;
 
+		/** @copydoc Physics::getMaxTesselationEdgeLength */
 		float getMaxTesselationEdgeLength() const override { return mTesselationLength; }
+
+		/** @copydoc Physics::setMaxTesselationEdgeLength */
 		void setMaxTesselationEdgeLength(float length) override;
 
+		/** @copydoc Physics::addBroadPhaseRegion */
 		UINT32 addBroadPhaseRegion(const AABox& region) override;
+
+		/** @copydoc Physics::removeBroadPhaseRegion */
 		void removeBroadPhaseRegion(UINT32 regionId) override;
+
+		/** @copydoc Physics::clearBroadPhaseRegions */
 		void clearBroadPhaseRegions() override;
 
 		/** @copydoc Physics::_boxOverlap */
@@ -175,29 +223,63 @@ namespace BansheeEngine
 		bool _rayCast(const Vector3& origin, const Vector3& unitDir, const Collider& collider, PhysicsQueryHit& hit, 
 			float maxDist = FLT_MAX) const override;
 
+		/** Triggered by the PhysX simulation when an interaction between two colliders is found. */
 		void _reportContactEvent(const ContactEvent& event);
+
+		/** Triggered by the PhysX simulation when an interaction between two trigger and a collider is found. */
 		void _reportTriggerEvent(const TriggerEvent& event);
+
+		/** Triggered by the PhysX simulation when a joint breaks. */
 		void _reportJointBreakEvent(const JointBreakEvent& event);
 
+		/** Returns the default PhysX material. */
 		physx::PxMaterial* getDefaultMaterial() const { return mDefaultMaterial; }
+
+		/** Returns the main PhysX object. */
 		physx::PxPhysics* getPhysX() const { return mPhysics; }
+
+		/** Returns the main PhysX scene. */
 		physx::PxScene* getScene() const { return mScene; }
+
+		/** Returns the PhysX object used for mesh cooking. */
 		physx::PxCooking* getCooking() const { return mCooking; }
+
+		/** Returns default scale used in the PhysX scene. */
 		physx::PxTolerancesScale getScale() const { return mScale; }
 
 	private:
 		friend class PhysXEventCallback;
 
+		/** Sends out all events recorded during simulation to the necessary physics objects. */
 		void triggerEvents();
 
-		// Scene query helpers
+		/**
+		 * Helper method that performs a sweep query by checking if the provided geometry hits any physics objects
+		 * when moved along the specified direction. Returns information about the first hit.
+		 */
 		inline bool sweep(const physx::PxGeometry& geometry, const physx::PxTransform& tfrm, const Vector3& unitDir,
 			PhysicsQueryHit& hit, UINT64 layer, float maxDist) const;
+
+		/**
+		 * Helper method that performs a sweep query by checking if the provided geometry hits any physics objects
+		 * when moved along the specified direction. Returns information about all hit.
+		 */
 		inline Vector<PhysicsQueryHit> sweepAll(const physx::PxGeometry& geometry, const physx::PxTransform& tfrm, 
 			const Vector3& unitDir, UINT64 layer, float maxDist) const;
+
+		/**
+		 * Helper method that performs a sweep query by checking if the provided geometry hits any physics objects
+		 * when moved along the specified direction. Returns no information about the hit, but rather just if it happened or
+		 * not.
+		 */
 		inline bool sweepAny(const physx::PxGeometry& geometry, const physx::PxTransform& tfrm, const Vector3& unitDir,
 			UINT64 layer, float maxDist) const;
-		inline Vector<Collider*> overlap(const physx::PxGeometry& geometry, const physx::PxTransform& tfrm, UINT64 layer) const;
+
+		/** Helper method that returns all colliders that are overlapping the provided geometry. */
+		inline Vector<Collider*> overlap(const physx::PxGeometry& geometry, const physx::PxTransform& tfrm, 
+			UINT64 layer) const;
+
+		/** Helper method that checks if the provided geometry overlaps any physics object. */
 		inline bool overlapAny(const physx::PxGeometry& geometry, const physx::PxTransform& tfrm, UINT64 layer) const;
 
 		float mSimulationStep = 1.0f/60.0f;
@@ -224,4 +306,6 @@ namespace BansheeEngine
 
 	/** Provides easier access to PhysX. */
 	PhysX& gPhysX();
+
+	/** @} */
 }

BansheePhysX/Include/BsPhysXCapsuleCollider.h

@@ -12,6 +12,7 @@ namespace BansheeEngine
 	 *  @{
 	 */
 
+	 /** PhysX implementation of a CapsuleCollider. */
 	class PhysXCapsuleCollider : public CapsuleCollider
 	{
 	public:

BansheePhysX/Include/BsPhysXPrerequisites.h

@@ -40,6 +40,11 @@ namespace BansheeEngine
 	class PhsyXMaterial;
 	class FPhysXCollider;
 
+	/** @cond INTERNAL */
+	/** @addtogroup PhysX
+	 *  @{
+	 */
+
 	/**	Type IDs used by the RTTI system for the PhysX library. */
 	enum TypeID_BansheeEditor
 	{
@@ -100,4 +105,7 @@ namespace BansheeEngine
 	/** @copydoc ObjectFilterFlag */
 	typedef Flags<PhysXObjectFilterFlag> PhysXObjectFilterFlags;
 	BS_FLAGS_OPERATORS(PhysXObjectFilterFlag)
+
+	/** @} */
+	/** @endcond */
 }