Added API documentation regarding compression.

library/PolyVoxCore/include/PolyVoxCore/Compressor.h

@@ -35,6 +35,10 @@ namespace PolyVox
 	 * The main purpose of this is to allow the user to change the compression algorithm which is used by a LargeVolume,
 	 * based on the kind of voxel data it is storing. Users may also wish to use Compressor subclasses in more general
 	 * compression-related scenarios but this is not well tested.
+	 *
+	 * If you wish to implement your own compression algorithms for use in PolyVox then you should begin by subclassing this class.
+	 *
+	 * \sa MinizCompressor, RLECompressor
 	 */
 	class Compressor
 	{
@@ -49,14 +53,43 @@ namespace PolyVox
 		/// If necessary you can use this as a destination buffer size, though it may be somewhat
 		/// wasteful. It is not guarenteed that compression actually shrinks the data, so the 
 		/// worst-case value returned by this function may be bigger than the input size.
-		/// \param The size of the uncompressed input data
+		///
+		/// \param uUncompressedInputSize The size of the uncompressed input data
 		/// \return The largest possible size of the compressed output data.
+		///
 		virtual uint32_t getMaxCompressedSize(uint32_t uUncompressedInputSize) = 0;
 
 		/// Compresses the data.
+		/// 
+		/// Performs compression of the data pointed to by pSrcData and stores the result in pDstData.
+		/// The user is responsible for allocating both buffers and for making sure that the destination
+		/// buffer is large enough to hold the result. If you don't know how big the compressed data
+		/// will be (and you probably won't know this) then you can call getMaxCompressedSize() to get
+		/// an upper bound. The *actual* compressed size is then returned by this function and you can
+		/// use this to copy your compressed data to a more suitably size buffer.
+		///
+		/// \param pSrcData A pointer to the data to be compressed.
+		/// \param uSrcLength The length of the data to be compressed.
+		/// \param pDstData A pointer to the memory where the result should be stored.
+		/// \param uDstLength The length of the destination buffer (compression will fail if this isn't big enough).
+		/// \return The size of the resulting compressed data.
+		///
 		virtual uint32_t compress(void* pSrcData, uint32_t uSrcLength, void* pDstData, uint32_t uDstLength) = 0;
 
 		/// Decompresses the data.
+		/// 
+		/// Performs decompression of the data pointed to by pSrcData and stores the result in pDstData.
+		/// The user is responsible for allocating both buffers and for making sure that the destination
+		/// buffer is large enough to hold the result. This means you need to know how large the resulting
+		/// data might be, so before you compress the data it may be worth storing this information somewhere.
+		/// The *actual* decompressed size is then returned by this function
+		///
+		/// \param pSrcData A pointer to the data to be decompressed.
+		/// \param uSrcLength The length of the data to be decompressed.
+		/// \param pDstData A pointer to the memory where the result should be stored.
+		/// \param uDstLength The length of the destination buffer (decompression will fail if this isn't big enough).
+		/// \return The size of the resulting uncompressed data.
+		///
 		virtual uint32_t decompress(void* pSrcData, uint32_t uSrcLength, void* pDstData, uint32_t uDstLength) = 0;
 	};
 }

library/PolyVoxCore/include/PolyVoxCore/MinizCompressor.h

@@ -5,12 +5,25 @@
 
 namespace PolyVox
 {
+	/**
+	 * Performs compression of data using the miniz library.
+	 *
+	 * This compressor implements the DEFLATE (http://en.wikipedia.org/wiki/Deflate) compression algorithm via the pubic domain 
+	 * 'miniz' library (https://code.google.com/p/miniz/). This is a general purpose compression algorithm, and within PolyVox it
+	 * is intended for situations in which the alternative RLECompressor is not appropriate. It is a good default choice if you
+	 * are not sure which compressor is best for your needs.
+	 * 
+	 * \sa RLECompressor
+	 */
 	class MinizCompressor : public Compressor
 	{
 	public:
+		/// Constructor
 		MinizCompressor(int iCompressionLevel = 6); // Miniz defines MZ_DEFAULT_LEVEL = 6 so we use the same here
+		/// Destructor
 		~MinizCompressor();
 		
+		// API documentation is in base class and gets inherited by Doxygen.
 		uint32_t getMaxCompressedSize(uint32_t uUncompressedInputSize);
 		uint32_t compress(void* pSrcData, uint32_t uSrcLength, void* pDstData, uint32_t uDstLength);
 		uint32_t decompress(void* pSrcData, uint32_t uSrcLength, void* pDstData, uint32_t uDstLength);

library/PolyVoxCore/include/PolyVoxCore/RLECompressor.h

@@ -5,6 +5,15 @@
 
 namespace PolyVox
 {
+	/**
+	 * Performs compression of data using Run Length Encoding (RLE).
+	 *
+	 * This compressor is designed for voxel data which contains long runs of the same value. Minecraft-style terrain and other
+	 * cubic-style terrains are likely to fall under this category, whereas density fields for Marching Cubes terrain will not. Please
+	 * see the following article if you want more details of how RLE compression works: http://en.wikipedia.org/wiki/Run-length_encoding
+	 *
+	 * \sa MinizCompressor
+	 */
 	template<typename ValueType, typename LengthType>
 	class RLECompressor : public Compressor
 	{
@@ -14,9 +23,12 @@ namespace PolyVox
 			LengthType length;
 		};
 	public:
+		/// Constructor
 		RLECompressor();
+		/// Destructor
 		~RLECompressor();
 
+		// API documentation is in base class and gets inherited by Doxygen.
 		uint32_t getMaxCompressedSize(uint32_t uUncompressedInputSize);
 		uint32_t compress(void* pSrcData, uint32_t uSrcLength, void* pDstData, uint32_t uDstLength);
 		uint32_t decompress(void* pSrcData, uint32_t uSrcLength, void* pDstData, uint32_t uDstLength);

library/PolyVoxCore/source/MinizCompressor.cpp

@@ -29,7 +29,9 @@ using namespace std;
 
 namespace PolyVox
 {
-	// Compression levels: 0-9 are the standard zlib-style levels, 10 is best possible compression (not zlib compatible, and may be very slow) 
+	/// You can specify a compression level when constructing this compressor. This controls the tradeoff between speed and compression
+	/// rate. Levels 0-9 are the standard zlib-style levels, 10 is best possible compression (not zlib compatible, and may be very slow).
+	/// \param iCompressionLevel The desired compression level.
 	MinizCompressor::MinizCompressor(int iCompressionLevel)
 		:m_pDeflator(0)
 	{