Updated doxygen comments on API functions

svn-id: r42166

5 files changed, 37 insertions, 13 deletions

diff --git a/common/system.h b/common/system.h
index 6f3dc6b6c8..b37797811a 100644
--- a/common/system.h
+++ b/common/system.h
@@ -376,8 +376,10 @@ public:
 	 *
 	 * @see Graphics::PixelFormat
 	 *
-	 * @note All backends supporting RGB color must be able to accept game data 
-	 *       in RGB color order, even if hardware uses BGR or some other color order.
+	 * @note Backends supporting RGB color should accept game data in RGB color 
+	 *       order, even if hardware uses BGR or some other color order.
+	 *
+	 * @see convertScreenRect
 	 */
 	virtual Common::List<Graphics::PixelFormat> getSupportedFormats() const = 0;
 #else
@@ -412,7 +414,7 @@ public:
 	 * This is the pixel format for which the client code generates data;
 	 * this is not necessarily equal to the hardware pixel format. For example,
 	 * a backend may perform color lookup of 8-bit graphics before pushing
-	 * a screen to hardware, or correct the ARGB color order.
+	 * a screen to hardware, or correct the ARGB color order via convertScreenRect.
 	 *
 	 * @param width		the new virtual screen width
 	 * @param height	the new virtual screen height
@@ -1026,6 +1028,8 @@ public:
 private:
 	/**
 	 * Convert a rectangle from the screen format to the hardware format.
+	 * Expected usage is for this to be called in copyRectToScreen when 
+	 * conversion is necessary.
 	 *
 	 * @param dstbuf	the buffer which will recieve the converted graphics data
 	 * @param srcbuf	the buffer containing the original graphics data
@@ -1040,7 +1044,9 @@ private:
 	 * @note This implementation is slow. Please override this if
 	 *		 your backend hardware has a better way to deal with this.
 	 * @note This implementation requires the screen pixel format and 
-	 *		 the hardware pixel format to have a matching bytedepth
+	 *		 the hardware pixel format to have a matching bytedepth.
+	 * @note This is meant for RGB modes only, do not attempt
+	 *		 to use it when running in 256 color mode.
 	 */
 	virtual bool convertScreenRect(byte *dstbuf, const byte *srcbuf, int dstpitch, int srcpitch, 
 									int w, int h, Graphics::PixelFormat hwFmt) {
diff --git a/engines/engine.h b/engines/engine.h
index c643d5895f..d570f18073 100644
--- a/engines/engine.h
+++ b/engines/engine.h
@@ -59,6 +59,8 @@ void initCommonGFX(bool defaultTo1XScaler);
  *
  * Errors out when backend is not able to switch to the specified
  * mode.
+ *
+ * Defaults to 256 color paletted mode if no graphics format is provided.
  */
 void initGraphics(int width, int height, bool defaultTo1xScaler, const Graphics::PixelFormat *format = NULL);
 
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) {