Add and cleanup some of the API documentation.

library/Doxyfile.in

@@ -224,7 +224,7 @@ OPTIMIZE_OUTPUT_VHDL   = NO
 # func(std::string) {}). This also make the inheritance and collaboration 
 # diagrams that involve STL classes more complete and accurate.
 
-BUILTIN_STL_SUPPORT    = NO
+BUILTIN_STL_SUPPORT    = YES
 
 # If you use Microsoft's C++/CLI language, you should set this option to YES to
 # enable parsing support.
@@ -244,7 +244,7 @@ SIP_SUPPORT            = NO
 # setting a simple type. If this is not the case, or you want to show the 
 # methods anyway, you should set this option to NO.
 
-IDL_PROPERTY_SUPPORT   = YES
+IDL_PROPERTY_SUPPORT   = NO
 
 # If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC 
 # tag is set to YES, then doxygen will reuse the documentation of the first 
@@ -373,7 +373,7 @@ INTERNAL_DOCS          = NO
 # in case and if your file system supports case sensitive file names. Windows 
 # and Mac users are advised to set this option to NO.
 
-CASE_SENSE_NAMES       = YES
+CASE_SENSE_NAMES       = NO
 
 # If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen 
 # will show members with their full class and namespace scopes in the 
@@ -642,8 +642,7 @@ RECURSIVE              = YES
 # excluded from the INPUT source files. This way you can easily exclude a 
 # subdirectory from a directory tree whose root is specified with the INPUT tag.
 
-EXCLUDE                = ${PolyVoxCore_SOURCE_DIR}/include/boost \
-                         ${PolyVoxCore_SOURCE_DIR}/include/PolyVoxImpl \
+EXCLUDE                = ${PolyVoxCore_SOURCE_DIR}/include/PolyVoxImpl \
                          ${PolyVoxCore_SOURCE_DIR}/source/PolyVoxImpl
 
 # The EXCLUDE_SYMLINKS tag can be used select whether or not files or 
@@ -909,7 +908,7 @@ DOCSET_BUNDLE_ID       = org.thermite3d.PolyVox
 # Microsoft HTML help workshop to generate a compiled HTML help file (.chm) 
 # of the generated HTML documentation.
 
-GENERATE_HTMLHELP      = YES
+GENERATE_HTMLHELP      = NO
 
 # If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can 
 # be used to specify the file name of the resulting .chm file. You 

library/PolyVoxCore/include/Array.h

@@ -50,6 +50,7 @@ namespace PolyVox
 	/// int height = 10;
 	/// int depth = 20;
 	///
+	/// //Creates a 3D array of integers with dimensions 5x10x20
 	/// Array<3, int> myArray(ArraySizes(width)(height)(depth));
 	///
 	/// int ct = 1;
@@ -66,13 +67,13 @@ namespace PolyVox
 	/// }
 	/// \endcode
 	///
-	/// Although the constructor and resize() function both take the required dimensions
+	/// Although the constructor and resize() functions both take the required dimensions
 	/// as an array of ints, note that the ArraySizes class can be used to build this
 	/// inline. This is a more convienient way of specifying these dimensions.
 	///
 	/// Note also that this class has a private assignment operator and copy constructor
 	/// in order to prevent copying. This is because a deep copy is a potentially slow
-	/// operation and can often be performed inadvertantly by functions such as std::swap,
+	/// operation and can often be performed inadvertently by functions such as std::swap,
 	/// while a shallow copy introduces confusion over memory ownership.
 	////////////////////////////////////////////////////////////////////////////////
 	template <uint32_t noOfDims, typename ElementType>

library/PolyVoxCore/include/Array.inl

@@ -25,7 +25,7 @@ namespace PolyVox
 {
 	////////////////////////////////////////////////////////////////////////////////
 	/// Creates an empty array with no elements. You will have to call resize() on this
-	/// array befire it can be used.
+	/// array before it can be used.
 	////////////////////////////////////////////////////////////////////////////////
 	template <uint32_t noOfDims, typename ElementType>
 	Array<noOfDims, ElementType>::Array()

library/PolyVoxCore/include/Log.h

@@ -34,9 +34,12 @@ freely, subject to the following restrictions:
 
 namespace PolyVox
 {
+	////////////////////////////////////////////////////////////////////////////////
+	/// Log levels for filtering logging events
+	////////////////////////////////////////////////////////////////////////////////
 	enum LogSeverity
 	{
-		LS_DEBUG,
+		LS_DEBUG, ///< Only displayed if it is a debug build
 		LS_INFO,
 		LS_WARN,
 		LS_ERROR

library/PolyVoxCore/include/Vector.h

@@ -34,7 +34,31 @@ freely, subject to the following restrictions:
 
 namespace PolyVox
 {
-    ///Represents a vector in space.    
+	/**
+	Represents a vector in space.
+	
+	This Vector class is templated on both size and data type. It is designed to be
+	generic but so far had only been tested with vectors of size 2 and 3. Also note
+	that some of the operations do not make sense with integer types, for example it
+	does not make conceptual sense to try and normalise an integer Vector.
+
+	The elements of the Vector are accessed via the overloaded () operator which takes
+	an index indicating the element to fetch. They are set using the set() function which
+	takes an index indicating the element to set and a new value for that element. For
+	convienience, the functions getX(), setX(), getY(), setY(), getZ(), setZ(), getw() and setW() 
+	do the same thing for the first 4 elements of the Vector. 
+
+	A variety of overloaded operators are also provided for comparison and arithmetic
+	operations. For most of these arithmetic operators only the unary versions are 
+	documented below - however often binary versions are also generated by std::operators.
+
+	Lastly, note that for convienience a set of typedefs are included for 2 and 3 dimensional
+	vectors with type float, double, int32_t, and uint32_t. They are used as follows:
+
+	\code
+	Vector2DInt4 test(1,2); //Declares a 2 dimensional Vector of type int4.
+	\endcode
+	*/
 	template <uint32_t Size, typename Type>
 	class Vector
     {

library/PolyVoxCore/include/Vector.inl

@@ -30,28 +30,6 @@ freely, subject to the following restrictions:
 
 namespace PolyVox
 {
-	/**
-	This Vector class is templated on both size and data type. It is designed to be
-	generic but so far had only been tested with vectors of size 2 and 3. Also note
-	that some of the operations do not make sense with integer types, for example it
-	does not make conceptual sense to try and normalise an integer Vector.
-
-	The elements of the Vector are accessed via the overloaded () operator which takes
-	an index indicating the element to fetch. They are set using the set() function which
-	takes an index indicating the element to set and a new value for that element. For
-	convienience, the functions getX(), setX(), getY(), setY(), getZ(), setZ, w() and setW() 
-	do the same thing for the first 4 elements of the Vector. 
-
-	A variety of overloaded operators are also provided for comparison and arithmetic
-	operations. For most of these arithmetic operators only the unary versions are 
-	documented below - however often binary versions are also generated by std::operators.
-
-	Lastly, note that for convienience a set of typedefs are included for 2 and 3 dimentionsal
-	vectors with type float, double, int32_t, and uint32_t. They are used as follows:
-
-	Vector2DInt4 test(1,2); //Declares a 2 dimensional Vector of type int4.
-	*/
-
 	#pragma region Constructors/Destructors
     //-------------------------- Constructors, etc ---------------------------------
     /**

library/PolyVoxCore/include/Volume.h

@@ -70,7 +70,7 @@ namespace PolyVox
 	/// -# Homogeneous blocks (those which contain just a single voxel value) are easy to
 	/// spot and fairly common becuase volumes often contain large homogeous regions. Any time
 	/// you change the value of a voxel you have potentially made the block which contains
-	/// it homogeneous. PolyVox does not check the homogeneity immediatly as this would slow
+	/// it homogeneous. PolyVox does not check the homogeneity immediately as this would slow
 	/// down the process of modifying voxels, but you can use the tidyUpMemory() function
 	/// to check for and remove duplicate homogeneous regions whenever you have spare
 	/// processing time.
@@ -87,23 +87,33 @@ namespace PolyVox
 	/// so we will not dwell on them here.
 	/// 
 	/// <b>Usage</b>
-	/// Volumes are constructed by passing the desired width height and depth to the
+	/// Volumes are constructed by passing the desired width, height and depth to the
 	/// constructor. Note that for speed reasons only values which are a power of two
 	/// are permitted for these sidelengths.
 	/// 
-	/// Access to specific voxels is provided by the getVoxelAt() and setVoxelAt fuctions.
+	/// \code
+	/// Volume<uint8_t> volData(g_uVolumeSideLength, g_uVolumeSideLength, g_uVolumeSideLength);
+	/// \endcode
+	/// 
+	/// Access to specific voxels is provided by the getVoxelAt() and setVoxelAt() fuctions.
 	/// Each of these has two forms so that voxels can be identified by integer triples
-	/// or by Vector3DUint16's.
+	/// or by Vector3DUint16%s.
+	/// 
+	/// \code
+	/// volData.setVoxelAt(12, 186, 281, 3);
+	/// uint8_t voxelValue = volData.getVoxelAt(12, 186, 281);
+	/// //voxelValue is now 3
+	/// \endcode
 	/// 
 	/// The tidyUpMemory() function should normally be called after you first populate
 	/// the volume with data, and then at periodic intervals as the volume is modified.
-	/// However, you don't actually <i>have</i> to call it at all. See the functions
+	/// However, you don't actually <i>have</i> to call it at all. See the function's
 	/// documentation for further details.
 	/// 
 	/// One further important point of note is that this class is templatised on the voxel
 	/// type. This allows you to store volumes of data types you might not normally expect,
-	/// for example theOpenGL example 'abuses' this class to store a 3D grid of pointers.
-	/// However, it is not guarentted that all functionality works correctly with non-integer
+	/// for example the OpenGL example 'abuses' this class to store a 3D grid of pointers.
+	/// However, it is not guaranteed that all functionality works correctly with non-integer
 	/// voxel types.
 	////////////////////////////////////////////////////////////////////////////////
 	template <typename VoxelType>
@@ -132,10 +142,14 @@ namespace PolyVox
 		uint16_t getShortestSideLength(void) const;
 		///Gets the length of the diagonal in voxels
 		float getDiagonalLength(void) const;
+		///Gets a voxel by <tt>x,y,z</tt> position
 		VoxelType getVoxelAt(uint16_t uXPos, uint16_t uYPos, uint16_t uZPos, VoxelType tDefault = VoxelType()) const;
+		///Gets a voxel by 3D vector position
 		VoxelType getVoxelAt(const Vector3DUint16& v3dPos, VoxelType tDefault = VoxelType()) const;
 
+		///Sets the voxel at an <tt>x,y,z</tt> position
 		bool setVoxelAt(uint16_t uXPos, uint16_t uYPos, uint16_t uZPos, VoxelType tValue);
+		///Sets the voxel at a 3D vector position
 		bool setVoxelAt(const Vector3DUint16& v3dPos, VoxelType tValue);
 
 		void tidyUpMemory(uint32_t uNoOfBlocksToProcess = (std::numeric_limits<uint32_t>::max)());

library/PolyVoxCore/include/Volume.inl

@@ -223,6 +223,13 @@ namespace PolyVox
 		return m_fDiagonalLength;
 	}
 
+	////////////////////////////////////////////////////////////////////////////////
+	/// \param uXPos the \c x position of the voxel
+	/// \param uYPos the \c y position of the voxel
+	/// \param uZPos the \c z position of the voxel
+	/// \param tDefault the voxel to be returned if the requested position is outside the volume
+	/// \return the voxel value
+	////////////////////////////////////////////////////////////////////////////////
 	template <typename VoxelType>
 	VoxelType Volume<VoxelType>::getVoxelAt(uint16_t uXPos, uint16_t uYPos, uint16_t uZPos, VoxelType tDefault) const
 	{
@@ -253,6 +260,11 @@ namespace PolyVox
 		}
 	}
 
+	////////////////////////////////////////////////////////////////////////////////
+	/// \param v3dPos the 3D position of the voxel
+	/// \param tDefault the voxel to be returned if the requested position is outside the volume
+	/// \return the voxel value
+	////////////////////////////////////////////////////////////////////////////////
 	template <typename VoxelType>
 	VoxelType Volume<VoxelType>::getVoxelAt(const Vector3DUint16& v3dPos, VoxelType tDefault) const
 	{
@@ -261,6 +273,13 @@ namespace PolyVox
 	#pragma endregion	
 
 	#pragma region Setters
+	////////////////////////////////////////////////////////////////////////////////
+	/// \param uXPos the \c x position of the voxel
+	/// \param uYPos the \c y position of the voxel
+	/// \param uZPos the \c z position of the voxel
+	/// \param tValue the value to which the voxel will be set
+	/// \return whether the requested position is inside the volume
+	////////////////////////////////////////////////////////////////////////////////
 	template <typename VoxelType>
 	bool Volume<VoxelType>::setVoxelAt(uint16_t uXPos, uint16_t uYPos, uint16_t uZPos, VoxelType tValue)
 	{
@@ -313,6 +332,11 @@ namespace PolyVox
 		}
 	}
 
+	////////////////////////////////////////////////////////////////////////////////
+	/// \param v3dPos the 3D position of the voxel
+	/// \param tValue the value to which the voxel will be set
+	/// \return whether the requested position is inside the volume
+	////////////////////////////////////////////////////////////////////////////////
 	template <typename VoxelType>
 	bool Volume<VoxelType>::setVoxelAt(const Vector3DUint16& v3dPos, VoxelType tValue)
 	{
@@ -321,6 +345,12 @@ namespace PolyVox
 	#pragma endregion
 
 	#pragma region Other
+	////////////////////////////////////////////////////////////////////////////////
+	/// Clean up the memory usage of the volume. Checks for any blocks which are
+	/// homogeneous and flags them as such for faster processing and reduced memory
+	/// usage.
+	/// \param uNoOfBlocksToProcess the number of blocks to process
+	////////////////////////////////////////////////////////////////////////////////
 	template <typename VoxelType>
 	void Volume<VoxelType>::tidyUpMemory(uint32_t uNoOfBlocksToProcess)
 	{