Add some Doxygen comments for broadphase and linearmath classes.

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 {