Updated doxygen comments on API functions

svn-id: r42166

3 files changed, 25 insertions, 9 deletions

diff --git a/graphics/conversion.h b/graphics/conversion.h
index 3226c38817..b0314046b9 100644
--- a/graphics/conversion.h
+++ b/graphics/conversion.h
@@ -48,7 +48,7 @@ inline static void RGB2YUV(byte r, byte g, byte b, byte &y, byte &u, byte &v) {
 // TODO: generic YUV to RGB blit
 
 /**
- * Convert a rectangle from the one format to another, and blits it.
+ * Blits a rectangle from one graphical format to another.
  *
  * @param dstbuf	the buffer which will recieve the converted graphics data
  * @param srcbuf	the buffer containing the original graphics data
@@ -61,8 +61,11 @@ inline static void RGB2YUV(byte r, byte g, byte b, byte &y, byte &u, byte &v) {
  * @return			true if conversion completes successfully,
  *					false if there is an error.
  *
- * @note This implementation currently requires the destination's
- *		 format have at least as high a bitdepth as the source's.
+ * @note This implementation currently arbitrarily requires that the 
+ *		 destination's format have at least as high a bytedepth as 
+ *		 the source's.
+ * @note This can convert a rectangle in place, if the source and 
+ *		 destination format have the same bytedepth.
  *
  */
 bool crossBlit(byte *dst, const byte *src, int dstpitch, int srcpitch,
diff --git a/graphics/cursorman.h b/graphics/cursorman.h
index ba11c9ef96..ae7008f54c 100644
--- a/graphics/cursorman.h
+++ b/graphics/cursorman.h
@@ -63,14 +63,14 @@ public:
 	 * safely freed afterwards.
 	 *
 	 * @param buf		the new cursor data
-	 * @param w		the width
-	 * @param h		the height
+	 * @param w			the width
+	 * @param h			the height
 	 * @param hotspotX	the hotspot X coordinate
 	 * @param hotspotY	the hotspot Y coordinate
 	 * @param keycolor	the index for the transparent color
 	 * @param targetScale	the scale for which the cursor is designed
-	 * @param format	the pixel format which the cursor graphic uses
-	 *
+	 * @param format	a pointer to the pixel format which the cursor graphic uses, 
+	 *					CLUT8 will be used if this is NULL or not specified.
 	 * @note It is ok for the buffer to be a NULL pointer. It is sometimes
 	 *       useful to push a "dummy" cursor and modify it later. The
 	 *       cursor will be added to the stack, but not to the backend.
@@ -95,7 +95,8 @@ public:
 	 * @param hotspotY	the hotspot Y coordinate
 	 * @param keycolor	the index for the transparent color
 	 * @param targetScale	the scale for which the cursor is designed
-	 * @param format	the pixel format which the cursor graphic uses
+	 * @param format	a pointer to the pixel format which the cursor graphic uses,
+	 *					CLUT8 will be used if this is NULL or not specified.
 	 */
 	void replaceCursor(const byte *buf, uint w, uint h, int hotspotX, int hotspotY, uint32 keycolor = 0xFFFFFFFF, int targetScale = 1, const Graphics::PixelFormat *format = NULL);
 
diff --git a/graphics/pixelformat.h b/graphics/pixelformat.h
index a1883291b9..bf18197f25 100644
--- a/graphics/pixelformat.h
+++ b/graphics/pixelformat.h
@@ -65,7 +65,11 @@ struct PixelFormat {
 		rShift = RShift, gShift = GShift, bShift = BShift, aShift = AShift;
 	}
 
-	// "Factory" methods for convenience
+	/////////////////////////////////////////////////////////
+	// Convenience functions for creating standard formats //
+	/////////////////////////////////////////////////////////
+
+	// 256 color palette.
 	static inline PixelFormat createFormatCLUT8() { 
 		return PixelFormat(1, 8, 8, 8, 8, 0, 0, 0, 0);
 	}
@@ -201,6 +205,14 @@ struct PixelFormat {
 	}
 };
 
+/**
+ * Determines the first matching format between two lists.
+ *
+ * @param backend	The higher priority list, meant to be a list of formats supported by the backend
+ * @param frontend	The lower priority list, meant to be a list of formats supported by the engine
+ * @return			The first item on the backend list that also occurs on the frontend list
+ *					or PixelFormat::createFormatCLUT8() if no matching formats were found.
+ */
 inline PixelFormat findCompatibleFormat(Common::List<PixelFormat> backend, Common::List<PixelFormat> frontend) {
 #ifdef ENABLE_RGB_COLOR
 	for (Common::List<PixelFormat>::iterator i = backend.begin(); i != backend.end(); ++i) {