Add some Doxygen comments for broadphase and linearmath classes.

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>

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:

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 ()

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
 	{
 	

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		*/ 

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
 {
 

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

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:

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:

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:

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
 {