GRAPHICS: Add some doxygen comments to Surface.

svn-id: r55142

1 files changed, 114 insertions, 9 deletions

diff --git a/graphics/surface.h b/graphics/surface.h
index 20ab816236..f9cb6cc474 100644
--- a/graphics/surface.h
+++ b/graphics/surface.h
@@ -35,55 +35,160 @@ namespace Graphics {
  * operations, font rendering, etc.
  */
 struct Surface {
+	/*
+	 * IMPORTANT implementation specific detail:
+	 *
+	 * ARM code relies on the layout of the first 3 of these fields. Do not
+	 * change them.
+	 */
+
 	/**
-	 * ARM code relies on the layout of the first 3 of these fields. Do
-	 * not change them.
+	 * The width of the surface.
 	 */
 	uint16 w;
+
+	/**
+	 * The height of the surface.
+	 */
 	uint16 h;
+
+	/**
+	 * The number of bytes a pixel line has.
+	 *
+	 * Note that this might not equal w * bytesPerPixel.
+	 */
 	uint16 pitch;
+
+	/**
+	 * The surface's pixel data.
+	 */
 	void *pixels;
+
+	/**
+	 * How many bytes a single pixel occupies.
+	 */
 	uint8 bytesPerPixel;
-	Surface() : w(0), h(0), pitch(0), pixels(0), bytesPerPixel(0) {}
 
+	/**
+	 * Construct a simple Surface object.
+	 */
+	Surface() : w(0), h(0), pitch(0), pixels(0), bytesPerPixel(0) {
+	}
+
+	/**
+	 * Return a pointer to the pixel at the specified point.
+	 *
+	 * @param x The x coordinate of the pixel.
+	 * @param y The y coordinate of the pixel.
+	 * @return Pointer to the pixel.
+	 */
 	inline const void *getBasePtr(int x, int y) const {
 		return (const byte *)(pixels) + y * pitch + x * bytesPerPixel;
 	}
 
+	/**
+	 * Return a pointer to the pixel at the specified point.
+	 *
+	 * @param x The x coordinate of the pixel.
+	 * @param y The y coordinate of the pixel.
+	 * @return Pointer to the pixel.
+	 */
 	inline void *getBasePtr(int x, int y) {
 		return static_cast<byte *>(pixels) + y * pitch + x * bytesPerPixel;
 	}
 
 	/**
-	 * Allocate pixels memory for this surface and for the specified dimension.
+	 * Allocate memory for the pixel data of the surface.
+	 *
+	 * Note that you are responsible for calling free yourself.
+	 * @see free
+	 *
+	 * @param width Width of the surface object.
+	 * @param height Height of the surface object.
+	 * @param bytePP The number of bytes a single pixel uses.
 	 */
 	void create(uint16 width, uint16 height, uint8 bytesPP);
 
 	/**
 	 * Release the memory used by the pixels memory of this surface. This is the
 	 * counterpart to create().
+	 *
+	 * Note that you should only use this, when you created the Surface data via
+	 * create! Otherwise this function has undefined behavior.
+	 * @see create
 	 */
 	void free();
 
 	/**
-	 * Copies data from another Surface, this calls *free* on the current surface, to assure
-	 * it being clean.
+	 * Copy the data from another Surface.
+	 *
+	 * Note that this calls free on the current surface, to assure it being
+	 * clean. So be sure the current data was created via create, otherwise
+	 * the results are undefined.
+	 * @see create
+	 * @see free
+	 *
+	 * @param surf Surface to copy from.
 	 */
 	void copyFrom(const Surface &surf);
 
+	/**
+	 * Draw a line.
+	 *
+	 * @param x0 The x coordinate of the start point.
+	 * @param y0 The y coordiante of the start point.
+	 * @param x1 The x coordinate of the end point.
+	 * @param y1 The y coordinate of the end point.
+	 * @param color The color of the line.
+	 */
 	void drawLine(int x0, int y0, int x1, int y1, uint32 color);
+
+	/**
+	 * Draw a horizontal line.
+	 *
+	 * @param x The start x coordinate of the line.
+	 * @param y The y coordiante of the line.
+	 * @param x2 The end x coordinate of the line.
+	 *           In case x > x2 the coordinates are swapped.
+	 * @param color The color of the line.
+	 */
 	void hLine(int x, int y, int x2, uint32 color);
+
+	/**
+	 * Draw a vertical line.
+	 *
+	 * @param x The x coordinate of the line.
+	 * @param y The start y coordiante of the line.
+	 * @param y2 The end y coordinate of the line.
+	 *           In case y > y2 the coordinates are swapped.
+	 * @param color The color of the line.
+	 */
 	void vLine(int x, int y, int y2, uint32 color);
+
+	/**
+	 * Fill a rect with a given color.
+	 *
+	 * @param r Rect to fill
+	 * @param color The color of the rect's contents.
+	 */
 	void fillRect(Common::Rect r, uint32 color);
+
+	/**
+	 * Draw a frame around a specified rect.
+	 *
+	 * @param r Rect to frame
+	 * @param color The color of the frame.
+	 */
 	void frameRect(const Common::Rect &r, uint32 color);
+
 	// See comment in graphics/surface.cpp about it
 	void move(int dx, int dy, int height);
 };
 
 /**
- * For safe deletion of surface with SharedPtr.
- * The deleter assures Surface::free is called on
- * deletion.
+ * A deleter for Surface objects which can be used with SharedPtr.
+ * 
+ * This deleter assures Surface::free is called on deletion.
  */
 struct SharedPtrSurfaceDeleter {
 	void operator()(Surface *ptr) {