diff --git a/src/BulletCollision/BroadphaseCollision/btAxisSweep3.h b/src/BulletCollision/BroadphaseCollision/btAxisSweep3.h
index 72ae4da3b..b807ddd9e 100644
--- a/src/BulletCollision/BroadphaseCollision/btAxisSweep3.h
+++ b/src/BulletCollision/BroadphaseCollision/btAxisSweep3.h
@@ -28,7 +28,8 @@
 
 //#define DEBUG_BROADPHASE 1
 
-/// btAxisSweep3Internal is an internal template class that implements sweep and prune.
+/// The internal templace class btAxisSweep3Internal implements the sweep and prune broadphase.
+/// It uses quantized integers to represent the begin and end points for each of the 3 axis.
 /// Dont use this class directly, use btAxisSweep3 or bt32BitAxisSweep3 instead.
 template <typename BP_FP_INT_TYPE>
 class btAxisSweep3Internal : public btBroadphaseInterface
@@ -884,9 +885,9 @@ void btAxisSweep3Internal<BP_FP_INT_TYPE>::sortMaxUp(int axis, BP_FP_INT_TYPE ed
 ////////////////////////////////////////////////////////////////////
 
 
-/// btAxisSweep3 is an efficient implementation of the 3d axis sweep and prune broadphase.
+/// The btAxisSweep3 is an efficient implementation of the 3d axis sweep and prune broadphase.
 /// It uses arrays rather then lists for storage of the 3 axis. Also it operates using 16 bit integer coordinates instead of floats.
-/// For large worlds and many objects, use bt32BitAxisSweep3 instead. bt32BitAxisSweep3 has higher precision and allows more then 16384 objects at the cost of more memory and bit of performance.
+/// For large worlds and many objects, use bt32BitAxisSweep3 or btDbvtBroadphase instead. bt32BitAxisSweep3 has higher precision and allows more then 16384 objects at the cost of more memory and bit of performance.
 class btAxisSweep3 : public btAxisSweep3Internal<unsigned short int>
 {
 public:
@@ -895,7 +896,7 @@ public:
 
 };
 
-/// bt32BitAxisSweep3 allows higher precision quantization and more objects compared to the btAxisSweep3 sweep and prune.
+/// The bt32BitAxisSweep3 allows higher precision quantization and more objects compared to the btAxisSweep3 sweep and prune.
 /// This comes at the cost of more memory per handle, and a bit slower performance.
 /// It uses arrays rather then lists for storage of the 3 axis.
 class bt32BitAxisSweep3 : public btAxisSweep3Internal<unsigned int>
diff --git a/src/BulletCollision/BroadphaseCollision/btBroadphaseInterface.h b/src/BulletCollision/BroadphaseCollision/btBroadphaseInterface.h
index 0f9a8d2fe..200ac3653 100644
--- a/src/BulletCollision/BroadphaseCollision/btBroadphaseInterface.h
+++ b/src/BulletCollision/BroadphaseCollision/btBroadphaseInterface.h
@@ -25,7 +25,9 @@ class btOverlappingPairCache;
 
 #include "LinearMath/btVector3.h"
 
-///BroadphaseInterface for aabb-overlapping object pairs
+///The btBroadphaseInterface class provides an interface to detect aabb-overlapping object pairs.
+///Some implementations for this broadphase interface include btAxisSweep3, bt32BitAxisSweep3 and btDbvtBroadphase.
+///The actual overlapping pair management, storage, adding and removing of pairs is dealt by the btOverlappingPairCache class.
 class btBroadphaseInterface
 {
 public:
diff --git a/src/BulletCollision/BroadphaseCollision/btBroadphaseProxy.h b/src/BulletCollision/BroadphaseCollision/btBroadphaseProxy.h
index 4e9b3f185..e0bb67f85 100644
--- a/src/BulletCollision/BroadphaseCollision/btBroadphaseProxy.h
+++ b/src/BulletCollision/BroadphaseCollision/btBroadphaseProxy.h
@@ -67,7 +67,8 @@ CONCAVE_SHAPES_END_HERE,
 };
 
 
-///btBroadphaseProxy
+///The btBroadphaseProxy is the main class that can be used with the Bullet broadphases. 
+///It stores collision shape type information, collision filter information and a client object, typically a btCollisionObject or btRigidBody.
 ATTRIBUTE_ALIGNED16(struct) btBroadphaseProxy
 {
 
@@ -148,7 +149,8 @@ struct btBroadphaseProxy;
 
 
 
-/// contains a pair of aabb-overlapping objects
+///The btBroadphasePair class contains a pair of aabb-overlapping objects.
+///A btDispatcher can search a btCollisionAlgorithm that performs exact/narrowphase collision detection on the actual collision shapes.
 ATTRIBUTE_ALIGNED16(struct) btBroadphasePair
 {
 	btBroadphasePair ()
diff --git a/src/BulletCollision/BroadphaseCollision/btDbvt.h b/src/BulletCollision/BroadphaseCollision/btDbvt.h
index fd7bdca34..76d8b9f10 100644
--- a/src/BulletCollision/BroadphaseCollision/btDbvt.h
+++ b/src/BulletCollision/BroadphaseCollision/btDbvt.h
@@ -181,9 +181,9 @@ struct	btDbvtNode
 		};
 };
 
-//
-// Dynamic bounding volume tree
-//
+///The btDbvt class implements a fast dynamic bounding volume tree based on axis aligned bounding boxes (aabb tree).
+///This btDbvt is used for soft body collision detection and for the btDbvtBroadphase. It has a fast insert, remove and update of nodes.
+///Unlike the btQuantizedBvh, nodes can be dynamically moved around, which allows for change in topology of the underlying data structure.
 struct	btDbvt
 	{
 	
diff --git a/src/BulletCollision/BroadphaseCollision/btDbvtBroadphase.h b/src/BulletCollision/BroadphaseCollision/btDbvtBroadphase.h
index 17d3d45fc..80b2936cb 100644
--- a/src/BulletCollision/BroadphaseCollision/btDbvtBroadphase.h
+++ b/src/BulletCollision/BroadphaseCollision/btDbvtBroadphase.h
@@ -52,9 +52,9 @@ btDbvtProxy(void* userPtr,short int collisionFilterGroup, short int collisionFil
 
 typedef btAlignedObjectArray<btDbvtProxy*>	btDbvtProxyArray;
 
-//
-// btDbvtBroadphase
-//
+///The btDbvtBroadphase implements a broadphase using two dynamic AABB bounding volume hierarchies/trees (see btDbvt).
+///One tree is used for static/non-moving objects, and another tree is used for dynamic objects. Objects can move from one tree to the other.
+///This is a very fast broadphase, especially for very dynamic worlds where many objects are moving. Its insert/add and remove of objects is generally faster than the sweep and prune broadphases btAxisSweep3 and bt32BitAxisSweep3.
 struct	btDbvtBroadphase : btBroadphaseInterface
 {
 /* Config		*/ 
diff --git a/src/BulletCollision/BroadphaseCollision/btDispatcher.h b/src/BulletCollision/BroadphaseCollision/btDispatcher.h
index 451265504..6db71a017 100644
--- a/src/BulletCollision/BroadphaseCollision/btDispatcher.h
+++ b/src/BulletCollision/BroadphaseCollision/btDispatcher.h
@@ -64,8 +64,8 @@ struct btDispatcherInfo
 	
 };
 
-/// btDispatcher can be used in combination with broadphase to dispatch overlapping pairs.
-/// For example for pairwise collision detection or user callbacks (game logic).
+///The btDispatcher interface class can be used in combination with broadphase to dispatch calculations for overlapping pairs.
+///For example for pairwise collision detection, calculating contact points stored in btPersistentManifold or user callbacks (game logic).
 class btDispatcher
 {
 
diff --git a/src/BulletCollision/BroadphaseCollision/btMultiSapBroadphase.h b/src/BulletCollision/BroadphaseCollision/btMultiSapBroadphase.h
index 44333e06d..b5c38ca42 100644
--- a/src/BulletCollision/BroadphaseCollision/btMultiSapBroadphase.h
+++ b/src/BulletCollision/BroadphaseCollision/btMultiSapBroadphase.h
@@ -26,7 +26,9 @@ class btSimpleBroadphase;
 
 typedef btAlignedObjectArray<btBroadphaseInterface*> btSapBroadphaseArray;
 
-///multi SAP broadphase
+///The btMultiSapBroadphase is a broadphase that contains multiple SAP broadphases.
+///The user can add SAP broadphases that cover the world. A btBroadphaseProxy can be in multiple child broadphases at the same time.
+///A btQuantizedBvh acceleration structures finds overlapping SAPs for each btBroadphaseProxy.
 ///See http://www.continuousphysics.com/Bullet/phpBB2/viewtopic.php?t=328
 ///and http://www.continuousphysics.com/Bullet/phpBB2/viewtopic.php?t=1329
 class btMultiSapBroadphase :public btBroadphaseInterface
diff --git a/src/BulletCollision/BroadphaseCollision/btOverlappingPairCache.h b/src/BulletCollision/BroadphaseCollision/btOverlappingPairCache.h
index 39dbf82e9..f91226c28 100644
--- a/src/BulletCollision/BroadphaseCollision/btOverlappingPairCache.h
+++ b/src/BulletCollision/BroadphaseCollision/btOverlappingPairCache.h
@@ -56,8 +56,8 @@ extern int gFindPairs;
 
 const int BT_NULL_PAIR=0xffffffff;
 
-///btOverlappingPairCache is an interface that allows different ways of pair management.
-///btHashedOverlappingPairCache or btSortedOverlappingPairCache are two implementations.
+///The btOverlappingPairCache provides an interface for overlapping pair management (add, remove, storage), used by the btBroadphaseInterface broadphases.
+///The btHashedOverlappingPairCache and btSortedOverlappingPairCache classes are two implementations.
 class btOverlappingPairCache : public btOverlappingPairCallback
 {
 public:
diff --git a/src/BulletCollision/BroadphaseCollision/btOverlappingPairCallback.h b/src/BulletCollision/BroadphaseCollision/btOverlappingPairCallback.h
index 078570bba..9c7b6f813 100644
--- a/src/BulletCollision/BroadphaseCollision/btOverlappingPairCallback.h
+++ b/src/BulletCollision/BroadphaseCollision/btOverlappingPairCallback.h
@@ -20,7 +20,7 @@ subject to the following restrictions:
 class btDispatcher;
 struct  btBroadphasePair;
 
-///btOverlappingPairCallback provides user callback to keep track of overlap between objects, like a collision sensor
+///The btOverlappingPairCallback class is an additional optional broadphase user callback for adding/removing overlapping pairs, similar interface to btOverlappingPairCache.
 class btOverlappingPairCallback
 {
 public:
diff --git a/src/BulletCollision/BroadphaseCollision/btQuantizedBvh.h b/src/BulletCollision/BroadphaseCollision/btQuantizedBvh.h
index 4828888cf..b98afc5a5 100644
--- a/src/BulletCollision/BroadphaseCollision/btQuantizedBvh.h
+++ b/src/BulletCollision/BroadphaseCollision/btQuantizedBvh.h
@@ -153,7 +153,9 @@ typedef btAlignedObjectArray<btQuantizedBvhNode>	QuantizedNodeArray;
 typedef btAlignedObjectArray<btBvhSubtreeInfo>		BvhSubtreeInfoArray;
 
 
-///OptimizedBvh store an AABB tree that can be quickly traversed on CPU (and SPU,GPU in future)
+///The btQuantizedBvh class stores an AABB tree that can be quickly traversed on CPU and Cell SPU.
+///It is used by the btBvhTriangleMeshShape as midphase, and by the btMultiSapBroadphase.
+///It is recommended to use quantization for better performance and lower memory requirements.
 ATTRIBUTE_ALIGNED16(class) btQuantizedBvh
 {
 protected:
diff --git a/src/BulletCollision/BroadphaseCollision/btSimpleBroadphase.h b/src/BulletCollision/BroadphaseCollision/btSimpleBroadphase.h
index 6013c6a16..49dfeb849 100644
--- a/src/BulletCollision/BroadphaseCollision/btSimpleBroadphase.h
+++ b/src/BulletCollision/BroadphaseCollision/btSimpleBroadphase.h
@@ -48,9 +48,8 @@ struct btSimpleBroadphaseProxy : public btBroadphaseProxy
 
 };
 
-///SimpleBroadphase is a brute force aabb culling broadphase based on O(n^2) aabb checks
-///btSimpleBroadphase is just a unit-test implementation to verify and test other broadphases.
-///So please don't use this class, but use bt32BitAxisSweep3 or btAxisSweep3 instead!
+///The SimpleBroadphase is just a unit-test for btAxisSweep3, bt32BitAxisSweep3, or btDbvtBroadphase, so use those classes instead.
+///It is a brute force aabb culling broadphase based on O(n^2) aabb checks
 class btSimpleBroadphase : public btBroadphaseInterface
 {
 
diff --git a/src/LinearMath/btAlignedAllocator.h b/src/LinearMath/btAlignedAllocator.h
index 0f6da30a5..87487d75e 100644
--- a/src/LinearMath/btAlignedAllocator.h
+++ b/src/LinearMath/btAlignedAllocator.h
@@ -52,6 +52,8 @@ typedef void (btFreeFunc)(void *memblock);
 void btAlignedAllocSetCustomAligned(btAlignedAllocFunc *allocFunc, btAlignedFreeFunc *freeFunc);
 void btAlignedAllocSetCustom(btAllocFunc *allocFunc, btFreeFunc *freeFunc);
 
+///The btAlignedAllocator is a portable class for aligned memory allocations.
+///Default implementations for unaligned and aligned allocations can be overridden by a custom allocator using btAlignedAllocSetCustom and btAlignedAllocSetCustomAligned.
 template < typename T , unsigned Alignment >
 class btAlignedAllocator {
 	
diff --git a/src/LinearMath/btAlignedObjectArray.h b/src/LinearMath/btAlignedObjectArray.h
index d65654411..ba52e2932 100644
--- a/src/LinearMath/btAlignedObjectArray.h
+++ b/src/LinearMath/btAlignedObjectArray.h
@@ -39,8 +39,8 @@ subject to the following restrictions:
 #endif //BT_USE_PLACEMENT_NEW
 
 
-///btAlignedObjectArray uses a subset of the stl::vector interface for its methods
-///It is developed to replace stl::vector to avoid STL alignment issues to add SIMD/SSE data
+///The btAlignedObjectArray template class uses a subset of the stl::vector interface for its methods
+///It is developed to replace stl::vector to avoid portability issues, including STL alignment issues to add SIMD/SSE data
 template <typename T> 
 //template <class T> 
 class btAlignedObjectArray
diff --git a/src/LinearMath/btConvexHull.h b/src/LinearMath/btConvexHull.h
index 1e3e1a74d..5caa73d89 100644
--- a/src/LinearMath/btConvexHull.h
+++ b/src/LinearMath/btConvexHull.h
@@ -183,6 +183,8 @@ public:
 
 
 
+///The HullLibrary class can create a convex hull from a collection of vertices, using the ComputeHull method.
+///The btShapeHull class uses this HullLibrary to create a approximate convex mesh given a general (non-polyhedral) convex shape.
 class HullLibrary
 {
 
diff --git a/src/LinearMath/btDefaultMotionState.h b/src/LinearMath/btDefaultMotionState.h
index bff31166e..f38be1bd2 100644
--- a/src/LinearMath/btDefaultMotionState.h
+++ b/src/LinearMath/btDefaultMotionState.h
@@ -1,7 +1,7 @@
 #ifndef DEFAULT_MOTION_STATE_H
 #define DEFAULT_MOTION_STATE_H
 
-///btDefaultMotionState provides a common implementation to synchronize world transforms with offsets
+///The btDefaultMotionState provides a common implementation to synchronize world transforms with offsets.
 struct	btDefaultMotionState : public btMotionState
 {
 	btTransform m_graphicsWorldTrans;
diff --git a/src/LinearMath/btGeometryUtil.h b/src/LinearMath/btGeometryUtil.h
index d8d3c197e..c18d6835f 100644
--- a/src/LinearMath/btGeometryUtil.h
+++ b/src/LinearMath/btGeometryUtil.h
@@ -19,6 +19,7 @@ subject to the following restrictions:
 #include "btVector3.h"
 #include "btAlignedObjectArray.h"
 
+///The btGeometryUtil helper class provides a few methods to convert between plane equations and vertices.
 class btGeometryUtil
 {
 	public:
diff --git a/src/LinearMath/btHashMap.h b/src/LinearMath/btHashMap.h
index 636ee064c..b1ce469af 100644
--- a/src/LinearMath/btHashMap.h
+++ b/src/LinearMath/btHashMap.h
@@ -78,6 +78,8 @@ public:
 	}
 };
 
+///The btHashMap template class implements a generic and lightweight hashmap.
+///A basic sample of how to use btHashMap is located in Demos\BasicDemo\main.cpp
 template <class Key, class Value>
 class btHashMap
 {
diff --git a/src/LinearMath/btIDebugDraw.h b/src/LinearMath/btIDebugDraw.h
index 15c50bdbf..563615a9a 100644
--- a/src/LinearMath/btIDebugDraw.h
+++ b/src/LinearMath/btIDebugDraw.h
@@ -31,6 +31,9 @@ DEALINGS IN THE SOFTWARE.
 #include "btVector3.h"
 
 
+///The btIDebugDraw interface class allows hooking up a debug renderer to visually debug simulations.
+///Typical use case: create a debug drawer object, and assign it to a btCollisionWorld or btDynamicsWorld using setDebugDrawer and call debugDrawWorld.
+///A class that implements the btIDebugDraw interface has to implement the drawLine method at a minimum.
 class	btIDebugDraw
 {
 	public:
diff --git a/src/LinearMath/btMatrix3x3.h b/src/LinearMath/btMatrix3x3.h
index 4c038d140..ca1a80140 100644
--- a/src/LinearMath/btMatrix3x3.h
+++ b/src/LinearMath/btMatrix3x3.h
@@ -22,6 +22,9 @@ subject to the following restrictions:
 #include "btQuaternion.h"
 
 
+
+///The btMatrix3x3 class implements a 3x3 rotation matrix, to perform linear algebra in combination with btQuaternion, btTransform and btVector3.
+///Make sure to only include a pure orthogonal matrix without scaling.
 class btMatrix3x3 {
 	public:
 		btMatrix3x3 () {}
diff --git a/src/LinearMath/btMotionState.h b/src/LinearMath/btMotionState.h
index e788b3d89..c97922665 100644
--- a/src/LinearMath/btMotionState.h
+++ b/src/LinearMath/btMotionState.h
@@ -18,7 +18,7 @@ subject to the following restrictions:
 
 #include "btTransform.h"
 
-///btMotionState allows the dynamics world to synchronize the updated world transforms with graphics
+///The btMotionState interface class allows the dynamics world to synchronize and interpolate the updated world transforms with graphics
 ///For optimizations, potentially only moving objects get synchronized (using setWorldPosition/setWorldOrientation)
 class	btMotionState
 {
diff --git a/src/LinearMath/btPoolAllocator.h b/src/LinearMath/btPoolAllocator.h
index d43bde7d4..8b0843c94 100755
--- a/src/LinearMath/btPoolAllocator.h
+++ b/src/LinearMath/btPoolAllocator.h
@@ -19,6 +19,7 @@ subject to the following restrictions:
 #include "btScalar.h"
 #include "btAlignedAllocator.h"
 
+///The btPoolAllocator class allows to efficiently allocate a large pool of objects, instead of dynamically allocating them separately.
 class btPoolAllocator
 {
 	int				m_elemSize;
diff --git a/src/LinearMath/btQuadWord.h b/src/LinearMath/btQuadWord.h
index 647b9eeeb..2e80fc2ca 100644
--- a/src/LinearMath/btQuadWord.h
+++ b/src/LinearMath/btQuadWord.h
@@ -21,9 +21,10 @@ subject to the following restrictions:
 #include <math.h>
 
 
-//ATTRIBUTE_ALIGNED16(class) btQuadWordStorage
-//some issues under PS3 Linux with IBM 2.1 SDK, gcc compiler prevent from using aligned quadword. todo: look into this
 
+///The btQuadWordStorage class is base class for btVector3 and btQuaternion. 
+///Some issues under PS3 Linux with IBM 2.1 SDK, gcc compiler prevent from using aligned quadword. todo: look into this
+///ATTRIBUTE_ALIGNED16(class) btQuadWordStorage
 class btQuadWordStorage
 {
 protected:
diff --git a/src/LinearMath/btQuaternion.h b/src/LinearMath/btQuaternion.h
index 2d1e79b9c..264751b33 100644
--- a/src/LinearMath/btQuaternion.h
+++ b/src/LinearMath/btQuaternion.h
@@ -19,6 +19,7 @@ subject to the following restrictions:
 
 #include "btVector3.h"
 
+///The btQuaternion implements quaternion to perform linear algebra rotations in combination with btMatrix3x3, btVector3 and btTransform.
 class btQuaternion : public btQuadWord {
 public:
 	btQuaternion() {}
diff --git a/src/LinearMath/btQuickprof.h b/src/LinearMath/btQuickprof.h
index ff1f0e005..b033940ca 100644
--- a/src/LinearMath/btQuickprof.h
+++ b/src/LinearMath/btQuickprof.h
@@ -54,7 +54,7 @@
 
 #define mymin(a,b) (a > b ? a : b)
 
-/// basic clock
+///The btClock is a portable basic clock that measures accurate time in seconds, use for profiling.
 class btClock
 {
 public:
@@ -229,9 +229,7 @@ private:
 
 
 
-/*
-** A node in the Profile Hierarchy Tree
-*/
+///A node in the Profile Hierarchy Tree
 class	CProfileNode {
 
 public:
@@ -266,9 +264,7 @@ protected:
 	CProfileNode *	Sibling;
 };
 
-/*
-** An iterator to navigate through the tree
-*/
+///An iterator to navigate through the tree
 class CProfileIterator
 {
 public:
@@ -302,9 +298,7 @@ protected:
 };
 
 
-/*
-** The Manager for the Profile system
-*/
+///The Manager for the Profile system
 class	CProfileManager {
 public:
 	static	void						Start_Profile( const char * name );
@@ -335,10 +329,8 @@ private:
 };
 
 
-/*
-** ProfileSampleClass is a simple way to profile a function's scope
-** Use the BT_PROFILE macro at the start of scope to time
-*/
+///ProfileSampleClass is a simple way to profile a function's scope
+///Use the BT_PROFILE macro at the start of scope to time
 class	CProfileSample {
 public:
 	CProfileSample( const char * name )
diff --git a/src/LinearMath/btScalar.h b/src/LinearMath/btScalar.h
index f3e27b98b..6447a1431 100644
--- a/src/LinearMath/btScalar.h
+++ b/src/LinearMath/btScalar.h
@@ -137,6 +137,7 @@ inline int	btGetVersion()
 #endif
 #endif
 
+///The btScalar type abstracts floating point numbers, to easily switch between double and single floating point precision.
 #if defined(BT_USE_DOUBLE_PRECISION)
 typedef double btScalar;
 #else
diff --git a/src/LinearMath/btStackAlloc.h b/src/LinearMath/btStackAlloc.h
index a2f7a53fd..5073a7864 100644
--- a/src/LinearMath/btStackAlloc.h
+++ b/src/LinearMath/btStackAlloc.h
@@ -29,7 +29,7 @@ struct btBlock
 	unsigned char*		address;
 };
 
-///StackAlloc provides some fast stack-based memory allocator (LIFO last-in first-out)
+///The StackAlloc class provides some fast stack-based memory allocator (LIFO last-in first-out)
 class btStackAlloc
 {
 public:
diff --git a/src/LinearMath/btTransform.h b/src/LinearMath/btTransform.h
index 168cf8623..a8cdb4281 100644
--- a/src/LinearMath/btTransform.h
+++ b/src/LinearMath/btTransform.h
@@ -21,7 +21,8 @@ subject to the following restrictions:
 #include "btMatrix3x3.h"
 
 
-///btTransform supports rigid transforms (only translation and rotation, no scaling/shear)
+///The btTransform class supports rigid transforms with only translation and rotation and no scaling/shear.
+///It can be used in combination with btVector3, btQuaternion and btMatrix3x3 linear algebra classes.
 class btTransform {