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
 {
 

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 {
 	

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

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
 {
 

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;

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:

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
 {

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:

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

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
 {

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;

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:

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

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 )

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

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:

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 {