diff --git a/doc/doxygen/groups.dox b/doc/doxygen/groups.dox
index 2a42ad93ac1..88e2b66d9b2 100644
--- a/doc/doxygen/groups.dox
+++ b/doc/doxygen/groups.dox
@@ -15,6 +15,13 @@
 
 /**
 
+@defgroup graphics Graphics API
+@brief API related to on-screen graphics - surfaces, pixels, cursors, fonts, palettes, and renderers.
+
+*/
+
+/**
+
 @defgroup image Image API
 @brief API of various image decoders used in engines.
 
diff --git a/graphics/cursorman.h b/graphics/cursorman.h
index 36215d03e2d..e0ca4141d35 100644
--- a/graphics/cursorman.h
+++ b/graphics/cursorman.h
@@ -31,19 +31,28 @@
 
 namespace Graphics {
 
+/**
+ * @defgroup graphics_cursorman Cursor manager
+ * @ingroup graphics
+ *
+ * @brief  The CursorManager class for managing the behavior of the mouse cursor.
+ *
+ * @{
+ */
+
 class CursorManager : public Common::Singleton<CursorManager> {
 public:
-	/** Query whether the mouse cursor is visible. */
+	/** Return whether the mouse cursor is visible. */
 	bool isVisible();
 
 	/**
 	 * Show or hide the mouse cursor.
 	 *
 	 * This function does not call OSystem::updateScreen, when visible is true.
-	 * This fact might result in a non visible mouse cursor if the caller does
-	 * not call OSystem::updateScreen itself after a showMouse(true) call.
+	 * You may need to call OSystem::updateScreen after a call to showMouse(true)
+	 * to ensure that the mouse cursor becomes visible.
 	 *
-	 * TODO: We might want to reconsider this behavior, it might be confusing
+	 * @todo We might want to reconsider this behavior, it might be confusing
 	 * for the user to call OSystem::updateScreen separately, on the other
 	 * hand OSystem::updateScreen might as well display unwanted changes on
 	 * the screen. Another alternative would be to let the backend worry
@@ -54,22 +63,24 @@ public:
 	bool showMouse(bool visible);
 
 	/**
-	 * Push a new cursor onto the stack, and set it in the backend. A local
-	 * copy will be made of the cursor data, so the original buffer can be
-	 * safely freed afterwards.
+	 * Push a new cursor onto the stack, and set it in the backend.
 	 *
-	 * @param buf		the new cursor data
-	 * @param w			the width
-	 * @param h			the height
-	 * @param hotspotX	the hotspot X coordinate
-	 * @param hotspotY	the hotspot Y coordinate
-	 * @param keycolor	the color value for the transparent color. This may not exceed
+	 * A local copy of the cursor data will be made, so the original buffer
+	 * can be safely freed afterwards.
+	 *
+	 * @param buf		New cursor data.
+	 * @param w			Width.
+	 * @param h			Height.
+	 * @param hotspotX	Hotspot X coordinate.
+	 * @param hotspotY	Hotspot Y coordinate.
+	 * @param keycolor	Color value for the transparent color. This cannot exceed
 	 *                  the maximum color value as defined by format.
-	 * @param dontScale	Whether the cursor should never be scaled. An exception are high ppi displays, where the cursor
-	 *                  would be too small to notice otherwise, these are allowed to scale the cursor anyway.
-	 * @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
+	 * @param dontScale	Whether the cursor should never be scaled. An exception are high PPI displays, where the cursor
+	 *                  would be too small to notice otherwise. These are allowed to scale the cursor anyway.
+	 * @param format	Pointer to the pixel format that the cursor graphic uses.
+	 *					CLUT8 will be used if this is null or not specified.
+	 *
+	 * @note It is acceptable 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.
 	 */
@@ -77,41 +88,46 @@ public:
 
 	/**
 	 * Pop a cursor from the stack, and restore the previous one to the
-	 * backend. If there is no previous cursor, the cursor is hidden.
+	 * backend.
+	 *
+	 * If there is no previous cursor, the cursor is hidden.
 	 */
 	void popCursor();
 
 	/**
-	 * Replace the current cursor on the stack. If the stack is empty, the
-	 * cursor is pushed instead. It's a slightly more optimized way of
-	 * popping the old cursor before pushing the new one.
+	 * Replace the current cursor on the stack.
 	 *
-	 * @param buf		the new cursor data
-	 * @param w		the width
-	 * @param h		the height
-	 * @param hotspotX	the hotspot X coordinate
-	 * @param hotspotY	the hotspot Y coordinate
-	 * @param keycolor	the color value for the transparent color. This may not exceed
+	 * If the stack is empty, the cursor is pushed instead. This is a slightly
+	 * more optimized way of popping the old cursor before pushing the new one.
+	 *
+	 * @param buf		New cursor data.
+	 * @param w			Width.
+	 * @param h			Height.
+	 * @param hotspotX	Hotspot X coordinate.
+	 * @param hotspotY	Hotspot Y coordinate.
+	 * @param keycolor	Color value for the transparent color. This cannot exceed
 	 *                  the maximum color value as defined by format.
-	 * @param dontScale	Whether the cursor should never be scaled. An exception are high ppi displays, where the cursor
-	 *                  would be too small to notice otherwise, these are allowed to scale the cursor anyway.
-	 * @param format	a pointer to the pixel format which the cursor graphic uses,
-	 *					CLUT8 will be used if this is NULL or not specified.
+	 * @param dontScale	Whether the cursor should never be scaled. An exception are high PPI displays, where the cursor
+	 *                  would be too small to notice otherwise. These are allowed to scale the cursor anyway.
+	 * @param format	Pointer to the pixel format that the cursor graphic uses,
+	 *					CLUT8 will be used if this is null or not specified.
 	 */
 	void replaceCursor(const void *buf, uint w, uint h, int hotspotX, int hotspotY, uint32 keycolor, bool dontScale = false, const Graphics::PixelFormat *format = NULL);
 
 	/**
-	 * Replace the current cursor on the stack. If the stack is empty, the
-	 * cursor is pushed instead. It's a slightly more optimized way of
-	 * popping the old cursor before pushing the new one.
+	 * Replace the current cursor on the stack.
 	 *
-	 * @param cursor	the new cursor
+	 * If the stack is empty, the cursor is pushed instead. This is a slightly
+	 * more optimized way of popping the old cursor before pushing the new one.
+	 *
+	 * @param cursor	New cursor.
 	 */
 	void replaceCursor(const Graphics::Cursor *cursor);
 
 	/**
-	 * Pop all of the cursors and cursor palettes from their respective stacks.
-	 * The purpose is to ensure that all unecessary cursors are removed from the
+	 * Pop all cursors and cursor palettes from their respective stacks.
+	 *
+	 * The purpose is to ensure that all unnecessary cursors are removed from the
 	 * stack when returning to the launcher from an engine.
 	 *
 	 */
@@ -120,8 +136,8 @@ public:
 	/**
 	 * Test whether cursor palettes are supported.
 	 *
-	 * This is just an convenience wrapper for checking for
-	 * OSystem::kFeatureCursorPalette to be supported by OSystem.
+	 * This is just an convenience wrapper for checking whether
+	 * OSystem::kFeatureCursorPalette is supported by OSystem.
 	 *
 	 * @see OSystem::kFeatureCursorPalette
 	 * @see OSystem::hasFeature
@@ -129,7 +145,7 @@ public:
 	bool supportsCursorPalettes();
 
 	/**
-	 * Enable/Disable the current cursor palette.
+	 * Enable or disable the current cursor palette.
 	 *
 	 * @param disable
 	 */
@@ -137,15 +153,16 @@ public:
 
 	/**
 	 * Push a new cursor palette onto the stack, and set it in the backend.
-	 * The palette entries from 'start' till (start+num-1) will be replaced
-	 * so a full palette updated is accomplished via start=0, num=256.
+	 *
+	 * The palette entries from @p start until @c (start+num-1) will be replaced
+	 * so a full palette update is accomplished via start=0, num=256.
 	 *
 	 * The palette data is specified in the same interleaved RGB format as
 	 * used by all backends.
 	 *
-	 * @param colors	the new palette data, in interleaved RGB format
-	 * @param start		the first palette entry to be updated
-	 * @param num		the number of palette entries to be updated
+	 * @param colors	New palette data, in interleaved RGB format.
+	 * @param start		First palette entry to be updated.
+	 * @param num		Number of palette entries to be updated.
 	 *
 	 * @note If num is zero, the cursor palette is disabled.
 	 */
@@ -153,26 +170,37 @@ public:
 
 	/**
 	 * Pop a cursor palette from the stack, and restore the previous one to
-	 * the backend. If there is no previous palette, the cursor palette is
-	 * disabled instead.
+	 * the backend.
+	 *
+	 * If there is no previous palette, the cursor palette is disabled instead.
 	 */
 	void popCursorPalette();
 
 	/**
-	 * Replace the current cursor palette on the stack. If the stack is
-	 * empty, the palette is pushed instead. It's a slightly more optimized
-	 * way of popping the old palette before pushing the new one.
+	 * Replace the current cursor palette on the stack.
 	 *
-	 * @param colors	the new palette data, in interleaved RGB format
-	 * @param start		the first palette entry to be updated
-	 * @param num		the number of palette entries to be updated
+	 * If the stack is empty, the palette is pushed instead. This is a slightly
+	 * more optimized way of popping the old palette before pushing the new one.
+	 *
+	 * @param colors	New palette data, in interleaved RGB format.
+	 * @param start		First palette entry to be updated.
+	 * @param num		Number of palette entries to be updated.
 	 *
 	 * @note If num is zero, the cursor palette is disabled.
 	 */
 	void replaceCursorPalette(const byte *colors, uint start, uint num);
 
+	/**
+	 * Lock or unlock the visibility state of the cursor.
+	 *
+	 * When the cursor is locked, calling showMouse(bool) does nothing
+	 * and returns false.
+	 */
 	void lock(bool locked);
 private:
+	/**
+	* Generic class for implementing the singleton design pattern.
+	*/
 	friend class Common::Singleton<SingletonBaseType>;
 	// Even though this is basically the default constructor we implement it
 	// ourselves, so it is private and thus there is no way to create this class
@@ -219,7 +247,7 @@ private:
 	Common::Stack<Palette *> _cursorPaletteStack;
 	bool _locked;
 };
-
+/** @} */
 } // End of namespace Graphics
 
 #define CursorMan	(::Graphics::CursorManager::instance())
diff --git a/graphics/font.h b/graphics/font.h
index 0da5571c3ce..112e0ef2e9b 100644
--- a/graphics/font.h
+++ b/graphics/font.h
@@ -33,35 +33,50 @@ template<class T> class Array;
 
 namespace Graphics {
 
+/**
+ * @defgroup graphics_font Fonts
+ * @ingroup graphics
+ *
+ * @brief API for representing and managing fonts on the screen.
+ *
+ * @{
+ */
+
 struct Surface;
 class ManagedSurface;
 
-/** Text alignment modes */
+/** Text alignment modes. */
 enum TextAlign {
-	kTextAlignInvalid,
-	kTextAlignStart,     ///< Text should be aligned to start of line (virtual)
-	kTextAlignLeft,     ///< Text should be aligned to the left
-	kTextAlignCenter,   ///< Text should be centered
-	kTextAlignEnd,     ///< Text should be aligned to end of line (virtual)
-	kTextAlignRight     ///< Text should be aligned to the right
+	kTextAlignInvalid,  ///< Indicates invalid alignment.
+	kTextAlignStart,    ///< Align the text to start of line (virtual).
+	kTextAlignLeft,     ///< Align the text to the left.
+	kTextAlignCenter,   ///< Center the text.
+	kTextAlignEnd,      ///< Align the text to end of line (virtual).
+	kTextAlignRight     ///< Align the text to the right.
 };
 
-/** Word wrapping modes */
+/** Word wrapping modes. */
 enum WordWrapMode {
-	kWordWrapDefault			= 0,
-	kWordWrapEvenWidthLines 	= 1 << 0,	///< Make the resulting line segments close to the same width
-	kWordWrapOnExplicitNewLines	= 1 << 1	///< Text is wrapped on new lines, otherwise treats them as single white space. Disables kWordWrapEvenWidthLines
+	kWordWrapDefault			= 0,		///< Default wrapping mode.
+	kWordWrapEvenWidthLines 	= 1 << 0,	///< Make the resulting line segments close to the same width.
+	kWordWrapOnExplicitNewLines	= 1 << 1	///< Text is wrapped on new lines. Otherwise, treats them as single whitespace. Disables kWordWrapEvenWidthLines.
 };
 
 /**
- * Converts virtual text alignments (start + end)
- * to actual text alignment (left + right + center) for drawing,
- * if given actual text alignments it is returned as-is
+ * Convert virtual text alignments (start + end)
+ * to actual text alignment (left + right + center) for drawing.
+ *
+ * If actual text alignment is provided, it is returned as-is.
+ *
+ * @param alignH  The horizontal alignment to convert.
+ * @param rtl     Indicates whether this is an RTL (right-to-left) language (such as Hebrew),
+ *                or a left-to-right language (such as English).
  */
 TextAlign convertTextAlignH(TextAlign alignH, bool rtl);
 
 /**
  * Instances of this class represent a distinct font, with a built-in renderer.
+ *
  * @todo Maybe move the high-level methods (drawString etc.) to a separate
  *       FontRenderer class? That way, we could have different variants... ?
  */
@@ -71,39 +86,42 @@ public:
 	virtual ~Font() {}
 
 	/**
-	 * Query the height of the font.
+	 * Return the height of the font.
 	 *
-	 * @return font height.
+	 * @return Font height in pixels.
 	 */
 	virtual int getFontHeight() const = 0;
 
 	/**
-	 * Query the maximum width of the font.
+	 * Return the maximum width of the font.
 	 *
-	 * @return maximum font width.
+	 * @return Maximum font width in pixels.
 	 */
 	virtual int getMaxCharWidth() const = 0;
 
 	/**
-	 * Query the width of a specific character.
+	 * Return the width of a specific character.
 	 *
-	 * @param chr The character to query the width of.
-	 * @return The character's width.
+	 * @param chr  The character to query the width of.
+	 *
+	 * @return The width of the character in pixels.
 	 */
 	virtual int getCharWidth(uint32 chr) const = 0;
 
 	/**
 	 * Query the kerning offset between two characters.
 	 *
-	 * @param left  The left character. May be 0.
-	 * @param right The right character. May be 0.
+	 * @param left   Left character. Can be 0.
+	 * @param right  Right character. Can be 0.
+	 *
 	 * @return The horizontal displacement.
 	 */
 	virtual int getKerningOffset(uint32 left, uint32 right) const;
 
 	/**
-	 * Calculate the bounding box of a character. It is assumed that
-	 * the character shall be drawn at position (0, 0).
+	 * Calculate the bounding box of a character.
+	 *
+	 * It is assumed that the character shall be drawn at position (0, 0).
 	 *
 	 * The idea here is that the character might be drawn outside the
 	 * rect (0, 0) to (getCharWidth(chr), getFontHeight()) for some fonts.
@@ -112,7 +130,8 @@ public:
 	 * The default implementation simply returns the rect with a width
 	 * of getCharWidth(chr) and height of getFontHeight().
 	 *
-	 * @param chr The character to draw.
+	 * @param chr  The character to draw.
+	 *
 	 * @return The bounding box of the drawn glyph.
 	 */
 	virtual Common::Rect getBoundingBox(uint32 chr) const;
@@ -120,54 +139,75 @@ public:
 	/**
 	 * Return the bounding box of a string drawn with drawString.
 	 *
-	 * @param x The x position where to start drawing
-	 * @param y The y position where to start drawing
-	 * @param w The width of the text area. This can be 0 to allow for
-	 *          obtaining the whole bounding box for a string. Note that this
-	 *          does not work with an align different from kTextAlignLeft or
-	 *          with useEllipsis.
-	 * @param align The text alignment. This can be used to center a string
-	 *              in the given area or to align it to the right.
-	 * @param delatx Offset to the x starting position of the string.
-	 * @param useEllipsis Try to fit the string in the area by inserting an
-	 *                    ellipsis. Be ware that the default is false for this
-	 *                    one unlike for drawString!
+	 * @param str     The drawn string.
+	 * @param x       The x position where to start drawing.
+	 * @param y       The y position where to start drawing.
+	 * @param w       Width of the text area. This can be 0 to allow for
+	 *                obtaining the whole bounding box for a string. Note that this
+	 *                does not work with an align different than kTextAlignLeft or
+	 *                with @p useEllipsis.
+	 * @param align   Text alignment. This can be used to center a string
+	 *                in the given area or to align it to the right.
+	 * @param deltax  Offset to the x starting position of the string.
+	 * @param useEllipsis  Try to fit the string in the area by inserting an
+	 *                     ellipsis. Note that the default value is false for this
+	 *                     argument, unlike for drawString.
+	 *  
 	 * @return The actual area where the string is drawn.
 	 */
 	Common::Rect getBoundingBox(const Common::String &str, int x = 0, int y = 0, const int w = 0, TextAlign align = kTextAlignLeft, int deltax = 0, bool useEllipsis = false) const;
+	/** @overload */
 	Common::Rect getBoundingBox(const Common::U32String &str, int x = 0, int _y = 0, const int w = 0, TextAlign align = kTextAlignLeft, int deltax = 0, bool useEllipsis = false) const;
 
 	/**
-	 * Draw a character at a specific point on a surface.
+	 * Draw a character at a specific point on the surface.
 	 *
 	 * Note that the point describes the top left edge point where to draw
-	 * the character. This can be different from top left edge point of the
-	 * character's bounding box! For example, TTF fonts sometimes move
-	 * characters like 't' one (or more) pixels to the left to create better
-	 * visual results. To query the actual bounding box of a character use
+	 * the character. This can be different from the top left edge point of the
+	 * character's bounding box. For example, TTF fonts sometimes move
+	 * characters like 't' by one (or more) pixels to the left to create better
+	 * visual results. To query the actual bounding box of a character, use
 	 * getBoundingBox.
 	 * @see getBoundingBox
 	 *
-	 * The Font implemenation should take care of not drawing outside of the
+	 * The Font implementation should take care of not drawing outside of the
 	 * specified surface.
 	 *
-	 * @param dst The surface to drawn on.
-	 * @param chr The character to draw.
-	 * @param x   The x coordinate where to draw the character.
-	 * @param y   The y coordinate where to draw the character.
+	 * @param dst   The surface to draw on.
+	 * @param chr   The character to draw.
+	 * @param x     The x coordinate where to draw the character.
+	 * @param y     The y coordinate where to draw the character.
 	 * @param color The color of the character.
 	 */
 	virtual void drawChar(Surface *dst, uint32 chr, int x, int y, uint32 color) const = 0;
+	/** @overload */
 	void drawChar(ManagedSurface *dst, uint32 chr, int x, int y, uint32 color) const;
 
-	// TODO: Add doxygen comments to this
+	/**
+	 * Draw the given @p str string to the given @p dst surface.
+	 *
+	 * @param dst     The surface on which to draw the string.
+	 * @param str     The string to draw.
+	 * @param x       The x position where to start drawing.
+	 * @param y       The y position where to start drawing.
+	 * @param w       Width of the text area.
+	 * @param color   The color with which to draw the string.
+	 * @param align   Text alignment. This can be used to center the string in the given area or to align it to the right.
+	 * @param deltax  Offset to the x starting position of the string.
+	 * @param useEllipsis  Use ellipsis if needed to fit the string in the area.
+	 *
+	 */
 	void drawString(Surface *dst, const Common::String &str, int x, int y, int w, uint32 color, TextAlign align = kTextAlignLeft, int deltax = 0, bool useEllipsis = true) const;
+	/** @overload */
 	void drawString(Surface *dst, const Common::U32String &str, int x, int y, int w, uint32 color, TextAlign align = kTextAlignLeft, int deltax = 0, bool useEllipsis = true) const;
+	/** @overload */
 	void drawString(ManagedSurface *dst, const Common::String &str, int x, int _y, int w, uint32 color, TextAlign align = kTextAlignLeft, int deltax = 0, bool useEllipsis = true) const;
+	/** @overload */
 	void drawString(ManagedSurface *dst, const Common::U32String &str, int x, int y, int w, uint32 color, TextAlign align = kTextAlignLeft, int deltax = 0, bool useEllipsis = true) const;
 
 	/**
-	 * Compute and return the width the string str has when rendered using this font.
+	 * Compute and return the width of the string @p str when rendered using this font.
+	 *
 	 * This describes the logical width of the string when drawn at (0, 0).
 	 * This can be different from the actual bounding box of the string. Use
 	 * getBoundingBox when you need the bounding box of a drawn string.
@@ -175,28 +215,32 @@ public:
 	 * @see drawChar
 	 */
 	int getStringWidth(const Common::String &str) const;
+	/** @overload */
 	int getStringWidth(const Common::U32String &str) const;
 
 	/**
-	 * Take a text (which may contain newline characters) and word wrap it so that
-	 * no text line is wider than maxWidth pixels. If necessary, additional line breaks
-	 * are generated, preferably between words (i.e. where whitespaces are).
-	 * The resulting lines are appended to the lines string list.
-	 * It returns the maximal width of any of the new lines (i.e. a value which is less
-	 * or equal to maxWidth).
+	 * Word-wrap a text (that can contain newline characters) so that
+	 * no text line is wider than @p maxWidth pixels.
 	 *
-	 * @param str       the string to word wrap
-	 * @param maxWidth  the maximum width a line may have
-	 * @param lines     the string list to which the text lines from str are appended
-	 * @param initWidth the starting width of the first line, for partially filled lines (optional)
-	 * @param mode		the wrapping mode. A bitfield of @ref WordWrapMode values
-	 * @return the maximal width of any of the lines added to lines
+	 * If necessary, additional line breaks are generated, preferably between
+	 * words, where whitespace is. The resulting lines are appended
+	 * to the @p lines string list. This returns the maximal width of any of the new
+	 * lines (i.e. a value that is smaller or equal to maxWidth).
+	 *
+	 * @param str        The string to word-wrap.
+	 * @param maxWidth   Maximum width that a line can have.
+	 * @param lines      The string list to which the text lines from @p str are appended.
+	 * @param initWidth  Starting width of the first line, for partially filled lines (optional).
+	 * @param mode		 Wrapping mode. A bitfield of @c WordWrapMode values.
+	 *
+	 * @return The maximal width of any of the lines added to @p lines.
 	 */
 	int wordWrapText(const Common::String &str, int maxWidth, Common::Array<Common::String> &lines, int initWidth = 0, uint32 mode = kWordWrapOnExplicitNewLines) const;
+	/** @overload */
 	int wordWrapText(const Common::U32String &str, int maxWidth, Common::Array<Common::U32String> &lines, int initWidth = 0, uint32 mode = kWordWrapOnExplicitNewLines) const;
 
 };
-
+/** @} */
 } // End of namespace Graphics
 
 #endif
diff --git a/graphics/managed_surface.h b/graphics/managed_surface.h
index c79122f31cc..c8838893254 100644
--- a/graphics/managed_surface.h
+++ b/graphics/managed_surface.h
@@ -30,143 +30,164 @@
 
 namespace Graphics {
 
+/**
+ * @defgroup graphics_managed_surface Managed surface
+ * @ingroup graphics
+ *
+ * @brief The ManagedSurface class that adds extra functionality on top of the Surface class.
+ *
+ * @{
+ */
+
 class Font;
 
 /**
- * A derived graphics surface, which handles automatically managing the allocated
- * surface data block, as well as introducing several new blitting methods
+ * A derived graphics surface, which supports automatically managing the allocated
+ * surface data block and introduces several new blitting methods.
  */
 class ManagedSurface {
+	/** See @ref Font. */
 	friend class Font;
 private:
 	/**
-	 * The Graphics::Surface that the managed surface encapsulates
+	 * The Graphics::Surface that the managed surface encapsulates.
 	 */
 	Surface _innerSurface;
 
 	/**
 	 * If set, the inner surface will be freed when the surface is recreated,
-	 * as well as when the surface is destroyed
+	 * as well as when the surface is destroyed.
 	 */
 	DisposeAfterUse::Flag _disposeAfterUse;
 
 	/**
-	 * Stores the owning surface if this If this managed surface represents
-	 * a sub-section of another
+	 * If this managed surface represents a subsection of another managed surface,
+	 * store the owning surface.
 	 */
 	ManagedSurface *_owner;
 
 	/**
-	 * For sub-section areas of an owning parent managed surface, this represents
-	 * the offset from the parent's top-left corner this sub-surface starts at
+	 * For a managed surface that has a parent, this represents the offset from
+	 * the parent's top-left corner where this sub-surface starts at.
 	 */
 	Common::Point _offsetFromOwner;
 
 	/**
-	 * Automatic transparency color. When set, doesn't require transparency to be
-	 * explicitly passed, and blit methods pass on to transBlit
+	 * Automatic transparency color. When set, it does not require transparency to be
+	 * explicitly passed, and blit methods pass on to transBlit.
 	 */
 	uint _transparentColor;
 	bool _transparentColorSet;
 
 	/**
-	 * Local palette for 8-bit images
+	 * Local palette for 8-bit images.
 	 */
 	uint32 _palette[256];
 	bool _paletteSet;
 protected:
 	/**
-	 * Base method that descendent classes can override for recording affected
-	 * dirty areas of the surface
+	 * Base method that descendant classes can override for recording the affected
+	 * dirty areas of the surface.
 	 */
 	virtual void addDirtyRect(const Common::Rect &r);
 
 	/**
-	 * Inner method for blitting
+	 * Inner method for blitting.
 	 */
 	void blitFromInner(const Surface &src, const Common::Rect &srcRect,
 		const Common::Point &destPos, const uint32 *palette);
 
 	/**
-	 * Inner method for copying another surface into this one at a given destination position
+	 * Inner method for copying another surface into this one at a given destination position.
 	 */
 	void transBlitFromInner(const Surface &src, const Common::Rect &srcRect,
 		const Common::Rect &destRect, uint transColor, bool flipped, uint overrideColor,
 		uint srcAlpha, const uint32 *srcPalette, const uint32 *dstPalette, const Surface *mask, bool maskOnly);
 public:
 	/**
-	 * Clips the given source bounds so the passed destBounds will be entirely on-screen
+	 * Clip the given source bounds so the passed destBounds will be entirely on-screen.
 	 */
 	bool clip(Common::Rect &srcBounds, Common::Rect &destBounds);
 public:
-	uint16 &w;
-	uint16 &h;
-	uint16 &pitch;
-	PixelFormat &format;
+	uint16 &w;           /*!< Width of the surface rectangle. */
+	uint16 &h;           /*!< Height of the surface rectangle. */
+	uint16 &pitch;       /*!< Pitch of the surface rectangle. See @ref Surface::pitch. */
+	PixelFormat &format; /*!< Pixel format of the surface. See @ref PixelFormat. */
 public:
 	/**
-	 * Create the managed surface
+	 * Create the managed surface.
 	 */
 	ManagedSurface();
 
 	/**
 	 * Create a managed surface from another one.
-	 * If the source surface is maintaining it's own surface data, then
-	 * this surface will create it's own surface of the same size and copy
-	 * the contents from the source surface
+	 *
+	 * If the source surface is maintaining its own surface data, then
+	 * this surface will create its own surface of the same size and copy
+	 * the contents from the source surface.
 	 */
 	ManagedSurface(const ManagedSurface &surf);
 
 	/**
-	 * Create the managed surface
+	 * Create the managed surface.
 	 */
 	ManagedSurface(int width, int height);
 
 	/**
-	 * Create the managed surface
+	 * Create the managed surface.
 	 */
 	ManagedSurface(int width, int height, const Graphics::PixelFormat &pixelFormat);
 
 	/**
-	 * Create the managed surface
+	 * Create the managed surface.
 	 */
 	ManagedSurface(ManagedSurface &surf, const Common::Rect &bounds);
 
 	/**
-	 * Destroy the managed surface
+	 * Destroy the managed surface.
 	 */
 	virtual ~ManagedSurface();
 
 	/**
-	 * Implements automatic conversion to a Graphics::Surface by
-	 * simply returning the inner surface. This must be const,
-	 * because we don't want changes being done directly to it,
-	 * since it would bypass dirty rect handling
+	 * Automatically convert to a Graphics::Surface by
+	 * simply returning the inner surface.
+	 *
+	 * This must be const, because changes are not supposed to be done
+	 * directly to it, since it would bypass dirty rect handling.
 	 */
 	operator const Surface &() const { return _innerSurface; }
+	/**
+	 * Automatically convert to a Graphics::Surface by
+	 * simply returning the inner surface.
+	 *
+	 * This must be const, because changes are not supposed to be done
+	 * directly to it, since it would bypass dirty rect handling.
+	 */
 	const Surface &rawSurface() const { return _innerSurface; }
 
 	/**
-	 * Reassign one managed surface to another one
-	 * Note that if the source has a managed surface, it will be duplicated
+	 * Reassign one managed surface to another one.
+	 *
+	 * @note If the source has a managed surface, it will be duplicated.
 	 */
 	ManagedSurface &operator=(const ManagedSurface &surf);
 
 	/**
-	 * Returns true if the surface has not yet been allocated
+	 * Return true if the surface has not yet been allocated.
 	 */
 	bool empty() const { return w == 0 || h == 0 || _innerSurface.getPixels() == nullptr; }
 
 	/**
-	 * Returns true if the surface is managing its own pixels
+	 * Return true if the surface manages its own pixels.
 	 */
 	DisposeAfterUse::Flag disposeAfterUse() const { return _disposeAfterUse; }
 
 	/**
 	 * 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.
+	 * @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 {
@@ -176,8 +197,9 @@ public:
 	/**
 	 * 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.
+	 * @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) {
@@ -185,13 +207,14 @@ public:
 	}
 
 	/**
-	 * Get a reference to the pixel data
+	 * Get a reference to the pixel data.
 	 */
 	inline void *getPixels() { return _innerSurface.getPixels(); }
+	/** @overload */
 	inline const void *getPixels() const { return _innerSurface.getPixels(); }
 
 	/**
-	 * Sets the pixel data.
+	 * Set the pixel data.
 	 */
 	virtual void setPixels(void *newPixels);
 
@@ -206,240 +229,256 @@ public:
 	virtual void create(uint16 width, uint16 height, const PixelFormat &pixelFormat);
 
 	/**
-	 * Sets up the surface as a sub-section of another passed parent surface. This surface
-	 * will not own the pixels, and any dirty rect notifications will automatically be
-	 * passed to the original parent surface.
-	 * @remarks		Note that this differs from Graphics::Surface::getSubArea, in that that
-	 * method only adds a single initial dirty rect for the whole area, and then none further
+	 * Set up the surface as a subsection of another passed parent surface.
+	 *
+	 * This surface will not own the pixels, and any dirty rect notifications will be
+	 * automatically passed to the original parent surface.
+	 *
+	 * @note This differs from Graphics::Surface::getSubArea, in that this
+	 * method only adds a single initial dirty rect for the whole area, and then none more.
 	 */
 	virtual void create(ManagedSurface &surf, const Common::Rect &bounds);
 
 	/**
-	 * Release the memory used by the pixels memory of this surface. This is the
-	 * counterpart to create().
+	 * Release the memory used by the pixel memory of this surface.
+	 *
+	 * This is a counterpart of create().
 	 */
 	virtual void free();
 
 	/**
-	 * Clears any pending dirty rects that have been generated for the surface
+	 * Clear any pending dirty rectangles that have been generated for the surface.
 	 */
 	virtual void clearDirtyRects() {}
 
 	/**
-	 * When the managed surface is a sub-section of a parent surface, returns the
-	 * the offset in the parent surface that the surface starts at
+	 * When the managed surface is a subsection of a parent surface, return the
+	 * the offset in the parent surface where the managed surface starts at.
 	 */
 	const Common::Point getOffsetFromOwner() const { return _offsetFromOwner; }
 
 	/**
-	 * Return a rect giving the bounds of the surface
+	 * Return a rect providing the bounds of the surface.
 	 */
 	const Common::Rect getBounds() const {
 		return Common::Rect(0, 0, this->w, this->h);
 	}
 
 	/**
-	 * Copies another surface into this one
+	 * Copy another surface into this one.
 	 */
 	void blitFrom(const Surface &src);
 
 	/**
-	 * Copies another surface into this one at a given destination position
+	 * Copy another surface into this one at a given destination position.
 	 */
 	void blitFrom(const Surface &src, const Common::Point &destPos);
 
 	/**
-	 * Copies another surface into this one at a given destination position
+	 * Copy another surface into this one at a given destination position.
 	 */
 	void blitFrom(const Surface &src, const Common::Rect &srcRect,
 		const Common::Point &destPos);
 
 	/**
-	 * Copies another surface into this one
+	 * Copy another surface into this one.
 	 */
 	void blitFrom(const ManagedSurface &src);
 
 	/**
-	 * Copies another surface into this one at a given destination position
+	 * Copy another surface into this one at a given destination position.
 	 */
 	void blitFrom(const ManagedSurface &src, const Common::Point &destPos);
 
 	/**
-	 * Copies another surface into this one at a given destination position
+	 * Copy another surface into this one at a given destination position.
 	 */
 	void blitFrom(const ManagedSurface &src, const Common::Rect &srcRect,
 		const Common::Point &destPos);
 
 	/**
-	 * Copies another surface into this one ignoring pixels of a designated transparent color
-	 * @param src			Source surface
-	 * @param transColor	Transparency color to ignore copying
-	 * @param flipped		Specifies whether to horizontally flip the image
+	 * Copy another surface into this one, ignoring pixels of a designated transparent color.
+	 *
+	 * @param src			Source surface.
+	 * @param transColor	Transparency color to ignore copying of.
+	 * @param flipped		Whether to horizontally flip the image.
 	 * @param overrideColor	Optional color to use instead of non-transparent pixels from
-	 *						the source surface
-	 * @param srcAlpha		Optional additional transparency applied to src
+	 *						the source surface.
+	 * @param srcAlpha		Optional additional transparency applied to @p src.
 	 */
 	void transBlitFrom(const Surface &src, uint transColor = 0, bool flipped = false,
 		uint overrideColor = 0, uint srcAlpha = 0xff);
 
 	/**
-	 * Copies another surface into this one ignoring pixels of a designated transparent color
-	 * @param src			Source surface
-	 * @param destPos		Destination position to draw the surface
-	 * @param transColor	Transparency color to ignore copying
-	 * @param flipped		Specifies whether to horizontally flip the image
+	 * Copy another surface into this one, ignoring pixels of a designated transparent color.
+	 *
+	 * @param src			Source surface.
+	 * @param destPos		Destination position to draw the surface.
+	 * @param transColor	Transparency color to ignore copying of.
+	 * @param flipped		Whether to horizontally flip the image.
 	 * @param overrideColor	Optional color to use instead of non-transparent pixels from
-	 *						the source surface
-	 * @param srcAlpha		Optional additional transparency applied to src
+	 *						the source surface.
+	 * @param srcAlpha		Optional additional transparency applied to @p src.
 	 */
 	void transBlitFrom(const Surface &src, const Common::Point &destPos,
 		uint transColor = 0, bool flipped = false, uint overrideColor = 0, uint srcAlpha = 0xff);
 
 	/**
-	 * Copies another surface into this one ignoring pixels of a designated transparent color
-	 * @param src			Source surface
-	 * @param destPos		Destination position to draw the surface
-	 * @param mask			Mask definition
+	 * Copy another surface into this one, ignoring pixels of a designated transparent color.
+	 *
+	 * @param src			Source surface.
+	 * @param destPos		Destination position to draw the surface.
+	 * @param mask			Mask definition.
 	 */
 	void transBlitFrom(const Surface &src, const Common::Point &destPos,
 		const ManagedSurface &mask);
 
 	/**
-	 * Copies another surface into this one ignoring pixels of a designated transparent color
-	 * @param src			Source surface
-	 * @param destPos		Destination position to draw the surface
-	 * @param mask			Mask definition
+	 * Copy another surface into this one, ignoring pixels of a designated transparent color.
+	 *
+	 * @param src			Source surface.
+	 * @param destPos		Destination position to draw the surface.
+	 * @param mask			Mask definition.
 	 */
 	void transBlitFrom(const Surface &src, const Common::Point &destPos,
 		const Surface &mask);
 
 	/**
-	 * Copies another surface into this one ignoring pixels of a designated transparent color
-	 * @param src			Source surface
-	 * @param srcRect		Sub-section of source surface to draw
-	 * @param destPos		Destination position to draw the surface
-	 * @param transColor	Transparency color to ignore copying
-	 * @param flipped		Specifies whether to horizontally flip the image
+	 * Copy another surface into this one, ignoring pixels of a designated transparent color.
+	 *
+	 * @param src			Source surface.
+	 * @param srcRect		Subsection of the source surface to draw.
+	 * @param destPos		Destination position to draw the surface.
+	 * @param transColor	Transparency color to ignore copying of.
+	 * @param flipped		Specifies whether to horizontally flip the image.
 	 * @param overrideColor	Optional color to use instead of non-transparent pixels from
-	 *						the source surface
-	 * @param srcAlpha		Optional additional transparency applied to src
+	 *						the source surface.
+	 * @param srcAlpha		Optional additional transparency applied to @p src.
 	 */
 	void transBlitFrom(const Surface &src, const Common::Rect &srcRect, const Common::Point &destPos,
 		uint transColor = 0, bool flipped = false, uint overrideColor = 0, uint srcAlpha = 0xff);
 
 	/**
-	 * Copies another surface into this one ignoring pixels of a designated transparent color
-	 * @param src			Source surface
-	 * @param srcRect		Sub-section of source surface to draw
+	 * Copy another surface into this one, ignoring pixels of a designated transparent color.
+	 *
+	 * @param src			Source surface.
+	 * @param srcRect		Subsection of the source surface to draw.
 	 * @param destRect		Destination area to draw the surface in. This can be sized differently
-	 *						then srcRect, allowing for arbitrary scaling of the image
-	 * @param transColor	Transparency color to ignore copying
-	 * @param flipped		Specifies whether to horizontally flip the image
+	 *						then @p srcRect, allowing for arbitrary scaling of the image.
+	 * @param transColor	Transparency color to ignore copying of.
+	 * @param flipped		Whether to horizontally flip the image.
 	 * @param overrideColor	Optional color to use instead of non-transparent pixels from
-	 *						the source surface
-	 * @param srcAlpha		Optional additional transparency applied to src
-	 * @param mask			Optional parameter with mask definition
-	 * @param maskOnly		Optional parameter for using mask over transColor
+	 *						the source surface.
+	 * @param srcAlpha		Optional additional transparency applied to @p src.
+	 * @param mask			Optional parameter with mask definition.
+	 * @param maskOnly		Optional parameter for using mask over @p transColor.
 	 */
 	void transBlitFrom(const Surface &src, const Common::Rect &srcRect, const Common::Rect &destRect,
 		uint transColor = 0, bool flipped = false, uint overrideColor = 0, uint srcAlpha = 0xff,
 		const Surface *mask = nullptr, bool maskOnly = false);
 
 	/**
-	 * Copies another surface into this one ignoring pixels of a designated transparent color
-	 * @param src			Source surface
-	 * @param transColor	Transparency color to ignore copying
-	 * @param flipped		Specifies whether to horizontally flip the image
+	 * Copy another surface into this one, ignoring pixels of a designated transparent color.
+	 *
+	 * @param src			Source surface.
+	 * @param transColor	Transparency color to ignore copying of.
+	 * @param flipped		Whether to horizontally flip the image.
 	 * @param overrideColor	Optional color to use instead of non-transparent pixels from
-	 *						the source surface
-	 * @param srcAlpha		Optional additional transparency applied to src
+	 *						the source surface.
+	 * @param srcAlpha		Optional additional transparency applied to @p src.
 	 */
 	void transBlitFrom(const ManagedSurface &src, uint transColor = 0, bool flipped = false,
 		uint overrideColor = 0, uint srcAlpha = 0xff);
 
 	/**
-	 * Copies another surface into this one ignoring pixels of a designated transparent color
-	 * @param src			Source surface
-	 * @param destPos		Destination position to draw the surface
-	 * @param transColor	Transparency color to ignore copying
-	 * @param flipped		Specifies whether to horizontally flip the image
+	 * Copy another surface into this one, ignoring pixels of a designated transparent color.
+	 *
+	 * @param src			Source surface.
+	 * @param destPos		Destination position to draw the surface.
+	 * @param transColor	Transparency color to ignore copying of.
+	 * @param flipped		Whether to horizontally flip the image.
 	 * @param overrideColor	Optional color to use instead of non-transparent pixels from
-	 *						the source surface
-	 * @param srcAlpha		Optional additional transparency applied to src
+	 *						the source surface.
+	 * @param srcAlpha		Optional additional transparency applied to @p src.
 	 */
 	void transBlitFrom(const ManagedSurface &src, const Common::Point &destPos,
 		uint transColor = 0, bool flipped = false, uint overrideColor = 0, uint srcAlpha = 0xff);
 
 	/**
-	 * Copies another surface into this one ignoring pixels of a designated transparent color
-	 * @param src			Source surface
-	 * @param destPos		Destination position to draw the surface
-	 * @param mask			Mask definition
+	 * Copy another surface into this one, ignoring pixels of a designated transparent color.
+	 *
+	 * @param src			Source surface.
+	 * @param destPos		Destination position to draw the surface.
+	 * @param mask			Mask definition.
 	 */
 	void transBlitFrom(const ManagedSurface &src, const Common::Point &destPos,
 		const ManagedSurface &mask);
 
 	/**
-	 * Copies another surface into this one ignoring pixels of a designated transparent color
-	 * @param src			Source surface
-	 * @param srcRect		Sub-section of source surface to draw
-	 * @param destPos		Destination position to draw the surface
-	 * @param transColor	Transparency color to ignore copying
-	 * @param flipped		Specifies whether to horizontally flip the image
+	 * Copy another surface into this one, ignoring pixels of a designated transparent color.
+	 *
+	 * @param src			Source surface.
+	 * @param srcRect		Subsection of the source surface to draw.
+	 * @param destPos		Destination position to draw the surface.
+	 * @param transColor	Transparency color to ignore copying of.
+	 * @param flipped		Whether to horizontally flip the image.
 	 * @param overrideColor	Optional color to use instead of non-transparent pixels from
-	 *						the source surface
-	 * @param srcAlpha		Optional additional transparency applied to src
+	 *						the source surface.
+	 * @param srcAlpha		Optional additional transparency applied to @p src.
 	 */
 	void transBlitFrom(const ManagedSurface &src, const Common::Rect &srcRect, const Common::Point &destPos,
 		uint transColor = 0, bool flipped = false, uint overrideColor = 0, uint srcAlpha = 0xff);
 
 	/**
-	 * Copies another surface into this one ignoring pixels of a designated transparent color
-	 * @param src			Source surface
-	 * @param srcRect		Sub-section of source surface to draw
+	 * Copy another surface into this one, ignoring pixels of a designated transparent color.
+	 *
+	 * @param src			Source surface.
+	 * @param srcRect		Subsection of the source surface to draw.
 	 * @param destRect		Destination area to draw the surface in. This can be sized differently
-	 *						then srcRect, allowing for arbitrary scaling of the image
-	 * @param transColor	Transparency color to ignore copying
-	 * @param flipped		Specifies whether to horizontally flip the image
+	 *						then @p srcRect, allowing for arbitrary scaling of the image.
+	 * @param transColor	Transparency color to ignore copying of.
+	 * @param flipped		Whether to horizontally flip the image.
 	 * @param overrideColor	Optional color to use instead of non-transparent pixels from
-	 *						the source surface
-	 * @param srcAlpha		Optional additional transparency applied to src
-	 * @param mask			Optional parameter with mask definition
-	 * @param maskOnly		Optional parameter for using mask over transColor
+	 *						the source surface.
+	 * @param srcAlpha		Optional additional transparency applied to @p src.
+	 * @param mask			Optional parameter with mask definition.
+	 * @param maskOnly		Optional parameter for using mask over @p transColor.
 	 */
 	void transBlitFrom(const ManagedSurface &src, const Common::Rect &srcRect, const Common::Rect &destRect,
 		uint transColor = 0, bool flipped = false, uint overrideColor = 0, uint srcAlpha = 0xff,
 		const Surface *mask = nullptr, bool maskOnly = false);
 
 	/**
-	 * Clear the entire surface
+	 * Clear the entire surface.
 	 */
 	void clear(uint color = 0);
 
 	/**
-	 * Mark the entire surface as dirty
+	 * Mark the entire surface as dirty.
 	 */
 	void markAllDirty();
 
 	/**
-	 * Copies a bitmap to the Surface internal buffer. The pixel format
-	 * of buffer must match the pixel format of the Surface.
+	 * Copy a bitmap to the internal buffer of the surface.
+	 *
+	 * The pixel format of the buffer must match the pixel format of the surface.
 	 */
 	void copyRectToSurface(const void *buffer, int srcPitch, int destX, int destY, int width, int height) {
 		_innerSurface.copyRectToSurface(buffer, srcPitch, destX, destY, width, height);
 	}
 
 	/**
-	 * Copies a bitmap to the Surface internal buffer. The pixel format
-	 * of buffer must match the pixel format of the Surface.
+	 * Copy a bitmap to the internal buffer of the surface.
+	 *
+	 * The pixel format of the buffer must match the pixel format of the surface.
 	 */
 	void copyRectToSurface(const Graphics::Surface &srcSurface, int destX, int destY, const Common::Rect subRect) {
 		_innerSurface.copyRectToSurface(srcSurface, destX, destY, subRect);
 	}
 
 	/**
-	 * Copy the data from another Surface, reinitializing the
-	 * surface to match the dimensions of the passed surface
+	 * Copy the data from another surface, reinitializing the
+	 * surface to match the dimensions of the passed surface.
 	 */
 	void copyFrom(const ManagedSurface &surf);
 
@@ -492,7 +531,7 @@ public:
 	}
 
 	/**
-	 * Returns a sub-area of the screen, but only adds a single initial dirty rect
+	 * Return a sub-area of the screen, but only add a single initial dirty rect
 	 * for the retrieved area.
 	 */
 	Surface getSubArea(const Common::Rect &area) {
@@ -503,24 +542,24 @@ public:
 	/**
 	 * Convert the data to another pixel format.
 	 *
-	 * This works in-place. This means it will not create an additional buffer
+	 * This works in-place. This means it does not create an additional buffer
 	 * for the conversion process. The value of 'pixels' might change though
 	 * (that means it might realloc the pixel data).
 	 *
-	 * @param dstFormat The desired format
-	 * @param palette   The palette (in RGB888), if the source format has a Bpp of 1
+	 * @param dstFormat  The desired format.
+	 * @param palette    The palette (in RGB888), if the source format has a bpp of 1.
 	 */
 	void convertToInPlace(const PixelFormat &dstFormat, const byte *palette = 0) {
 		_innerSurface.convertToInPlace(dstFormat, palette);
 	}
 
 	/**
-	 * Returns the current transparent color
+	 * Return the current transparent color.
 	 */
 	uint getTransparentColor() const { return _transparentColor; }
 
 	/**
-	 * Sets the transparent color
+	 * Set the transparent color.
 	 */
 	void setTransparentColor(uint color) {
 		_transparentColor = color;
@@ -528,44 +567,44 @@ public:
 	}
 
 	/**
-	 * Clears the transparent color setting
+	 * Clear the transparent color setting.
 	 */
 	void clearTransparentColor() {
 		_transparentColorSet = false;
 	}
 
 	/**
-	 * Returns true if a transparent color has been set
+	 * Return true if a transparent color has been set.
 	 */
 	bool hasTransparentColor() const {
 		return _transparentColorSet;
 	}
 
 	/**
-	 * Clear any existing palette
+	 * Clear any existing palette.
 	 */
 	void clearPalette() {
 		_paletteSet = false;
 	}
 
 	/**
-	 * Gets the palette array
+	 * Get the palette array.
 	 */
 	const uint32 *getPalette() const {
 		return _palette;
 	}
 
 	/**
-	 * Sets the palette using RGB tuplets
+	 * Set the palette using RGB tuples.
 	 */
 	void setPalette(const byte *colors, uint start, uint num);
 
 	/**
-	 * Sets the palette using RGBA values
+	 * Set the palette using RGBA values.
 	 */
 	void setPalette(const uint32 *colors, uint start, uint num);
 };
-
+/** @} */
 } // End of namespace Graphics
 
 #endif
diff --git a/graphics/pixelformat.h b/graphics/pixelformat.h
index f3e7f95a6b1..5c0137c7885 100644
--- a/graphics/pixelformat.h
+++ b/graphics/pixelformat.h
@@ -28,18 +28,27 @@
 
 namespace Graphics {
 
-/** Template to expand from an n-bit component to an 8-bit component */
+/**
+ * @defgroup graphics_pixelformat Pixel formats
+ * @ingroup graphics
+ *
+ * @brief Structures for managing pixel formats.
+ *
+ * @{
+ */
+
+/** Template to expand from an n-bit component to an 8-bit component. */
 template<int depth>
 struct ColorComponent {
 };
-
+/** Return 0 for an empty color component. */
 template<>
 struct ColorComponent<0> {
 	static inline uint expand(uint value) {
 		return 0;
 	}
 };
-
+/** Template to expand a 1-bit component into an 8-bit component. */
 template<>
 struct ColorComponent<1> {
 	static inline uint expand(uint value) {
@@ -54,7 +63,7 @@ struct ColorComponent<1> {
 		       (value << 7);
 	}
 };
-
+/** Template to expand a 2-bit component into an 8-bit component. */
 template<>
 struct ColorComponent<2> {
 	static inline uint expand(uint value) {
@@ -65,7 +74,7 @@ struct ColorComponent<2> {
 		       (value << 6);
 	}
 };
-
+/** Template to expand a 3-bit component into an 8-bit component. */
 template<>
 struct ColorComponent<3> {
 	static inline uint expand(uint value) {
@@ -75,7 +84,7 @@ struct ColorComponent<3> {
 		       (value >> 1);
 	}
 };
-
+/** Template to expand a 4-bit component into an 8-bit component. */
 template<>
 struct ColorComponent<4> {
 	static inline uint expand(uint value) {
@@ -84,7 +93,7 @@ struct ColorComponent<4> {
 		       (value << 4);
 	}
 };
-
+/** Template to expand a 5-bit component into an 8-bit component. */
 template<>
 struct ColorComponent<5> {
 	static inline uint expand(uint value) {
@@ -93,7 +102,7 @@ struct ColorComponent<5> {
 		       (value >> 2);
 	}
 };
-
+/** Template to expand a 6-bit component into an 8-bit component. */
 template<>
 struct ColorComponent<6> {
 	static inline uint expand(uint value) {
@@ -102,7 +111,7 @@ struct ColorComponent<6> {
 		       (value >> 4);
 	}
 };
-
+/** Template to expand a 7-bit component into an 8-bit component. */
 template<>
 struct ColorComponent<7> {
 	static inline uint expand(uint value) {
@@ -111,7 +120,7 @@ struct ColorComponent<7> {
 		       (value >> 6);
 	}
 };
-
+/** Return the given value. */
 template<>
 struct ColorComponent<8> {
 	static inline uint expand(uint value) {
@@ -120,17 +129,17 @@ struct ColorComponent<8> {
 };
 
 /**
- * A pixel format description.
+ * Pixel format description.
  *
- * Like ColorMasks it includes the given values to create colors from RGB
+ * Like ColorMasks, it includes the given values to create colors from RGB
  * values and to retrieve RGB values from colors.
  *
- * Unlike ColorMasks it is not dependend on knowing the exact pixel format
+ * Unlike ColorMasks, it is not dependent on knowing the exact pixel format
  * on compile time.
  *
  * A minor difference between ColorMasks and PixelFormat is that ColorMasks
- * stores the bit count per channel in 'kFooBits', while PixelFormat stores
- * the loss compared to 8 bits per channel in '#Loss'. It also doesn't
+ * stores the bit count per channel in @c kFooBits, while PixelFormat stores
+ * the loss compared to 8 bits per channel in @c \#Loss. It also does not
  * contain mask values.
  */
 struct PixelFormat {
@@ -139,12 +148,31 @@ struct PixelFormat {
 	byte rLoss, gLoss, bLoss, aLoss; /**< Precision loss of each color component. */
 	byte rShift, gShift, bShift, aShift; /**< Binary left shift of each color component in the pixel value. */
 
+	/** Default constructor that creates a null pixel format. */
 	inline PixelFormat() {
 		bytesPerPixel =
 		rLoss = gLoss = bLoss = aLoss =
 		rShift = gShift = bShift = aShift = 0;
 	}
 
+	/** Construct a pixel format based on the provided arguments.
+	 *  
+	 *  Examples:
+	 *  
+	 *  - RGBA8888:
+	 *  @code
+	 *  BytesPerPixel = 4, RBits = GBits = BBits = ABits = 8, RShift = 24, GShift = 16, BShift = 8, AShift = 0
+	 *  @endcode
+	 *  - ABGR8888:
+	 *  @code
+	 *  BytesPerPixel = 4, RBits = GBits = BBits = ABits = 8, RShift = 0, GShift = 8, BShift = 16, AShift = 24
+	 *  @endcode
+	 *  - RGB565:
+	 *  @code
+	 *  BytesPerPixel = 2, RBits = 5, GBits = 6, BBits = 5, ABits = 0, RShift = 11, GShift = 5, BShift = 0, AShift = 0
+	 *  @endcode
+	 */
+
 	inline PixelFormat(byte BytesPerPixel,
 						byte RBits, byte GBits, byte BBits, byte ABits,
 						byte RShift, byte GShift, byte BShift, byte AShift) {
@@ -159,10 +187,12 @@ struct PixelFormat {
 		aShift = AShift;
 	}
 
+	/** Define a CLUT8 pixel format. */
 	static inline PixelFormat createFormatCLUT8() {
 		return PixelFormat(1, 0, 0, 0, 0, 0, 0, 0, 0);
 	}
 
+	/** Check if two pixel formats are the same */
 	inline bool operator==(const PixelFormat &fmt) const {
 		// TODO: If aLoss==8, then the value of aShift is irrelevant, and should be ignored.
 		return bytesPerPixel == fmt.bytesPerPixel &&
@@ -176,10 +206,12 @@ struct PixelFormat {
 		       aShift == fmt.aShift;
 	}
 
+	/** Check if two pixel formats are different. */
 	inline bool operator!=(const PixelFormat &fmt) const {
 		return !(*this == fmt);
 	}
 
+	/** Return an RGB color value from red, green, and blue values. */
 	inline uint32 RGBToColor(uint8 r, uint8 g, uint8 b) const {
 		return
 			((0xFF >> aLoss) << aShift) |
@@ -188,6 +220,7 @@ struct PixelFormat {
 			((   b >> bLoss) << bShift);
 	}
 
+	/** Return an ARGB color value from alpha, red, green, and blue values. */
 	inline uint32 ARGBToColor(uint8 a, uint8 r, uint8 g, uint8 b) const {
 		return
 			((a >> aLoss) << aShift) |
@@ -196,12 +229,14 @@ struct PixelFormat {
 			((b >> bLoss) << bShift);
 	}
 
+	/** Retrieve red, green, and blue values from an RGB color value. */
 	inline void colorToRGB(uint32 color, uint8 &r, uint8 &g, uint8 &b) const {
 		r = expand(rBits(), color >> rShift);
 		g = expand(gBits(), color >> gShift);
 		b = expand(bBits(), color >> bShift);
 	}
 
+	/** Retrieve alpha, red, green, and blue values from an ARGB color value. */
 	inline void colorToARGB(uint32 color, uint8 &a, uint8 &r, uint8 &g, uint8 &b) const {
 		a = (aBits() == 0) ? 0xFF : expand(aBits(), color >> aShift);
 		r = expand(rBits(), color >> rShift);
@@ -209,51 +244,81 @@ struct PixelFormat {
 		b = expand(bBits(), color >> bShift);
 	}
 
-	//////////////////////////////////////////////////////////////////////
-	// Convenience functions for getting number of color component bits //
-	//////////////////////////////////////////////////////////////////////
+	/**
+	 * @name Convenience functions for getting the number of color component bits
+	 * @{
+	 */
 
+	/**
+	 * Return the number of red component bits.
+	 */
 	inline byte rBits() const {
 		return (8 - rLoss);
 	}
 
+	/**
+	 * Return the number of green component bits.
+	 */
 	inline byte gBits() const {
 		return (8 - gLoss);
 	}
 
+	/**
+	 * Return the number of blue component bits.
+	 */
 	inline byte bBits() const {
 		return (8 - bLoss);
 	}
 
+	/**
+	 * Return the number of alpha component bits.
+	 */
 	inline byte aBits() const {
 		return (8 - aLoss);
 	}
 
+	/**
+	 * Return the total number of bits for the pixel format.
+	 */
 	inline byte bpp() const {
 		return rBits() + gBits() + bBits() + aBits();
 	}
+	/** @} */
+	 
+	/**
+	 * @name Convenience functions for getting color components' maximum values
+	 * @{ 
+	 */
 
-	////////////////////////////////////////////////////////////////////////
-	// Convenience functions for getting color components' maximum values //
-	////////////////////////////////////////////////////////////////////////
-
+	/**
+	 * Return the maximum value of red.
+	 */
 	inline uint rMax() const {
 		return (1 << rBits()) - 1;
 	}
 
+	/**
+	 * Return the maximum value of green.
+	 */
 	inline uint gMax() const {
 		return (1 << gBits()) - 1;
 	}
 
+	/**
+	 * Return the maximum value of blue.
+	 */
 	inline uint bMax() const {
 		return (1 << bBits()) - 1;
 	}
 
+	/**
+	 * Return the maximum value of alpha.
+	 */
 	inline uint aMax() const {
 		return (1 << aBits()) - 1;
 	}
-
-	/** Expand a given bit-depth component to a full 8-bit component */
+	/** @} */
+	/** Expand a given bit-depth component to a full 8-bit component. @todo is that different from the templates at the beginning? */
 	static inline uint expand(uint bits, uint color) {
 		switch (bits) {
 		case 0:
@@ -281,10 +346,10 @@ struct PixelFormat {
 		// Unsupported
 		return 0;
 	}
-
+	/** Return string representation. */
 	Common::String toString() const;
 };
-
+/** @} */
 } // End of namespace Graphics
 
 #endif
diff --git a/graphics/surface.h b/graphics/surface.h
index b7ada5ec28a..e4d10ee0070 100644
--- a/graphics/surface.h
+++ b/graphics/surface.h
@@ -36,43 +36,52 @@ struct Point;
 namespace Graphics {
 
 /**
- * An arbitrary graphics surface, which can be the target (or source) of blit
+ * @defgroup graphics_surface Surface
+ * @ingroup graphics
+ *
+ * @brief Surface class for managing an arbitrary graphics surface.
+ *
+ * @{
+ */
+
+/**
+ * An arbitrary graphics surface that can be the target (or source) of blit
  * operations, font rendering, etc.
  */
 struct Surface {
 	/*
-	 * IMPORTANT implementation specific detail:
+	 * IMPORTANT implementation-specific detail:
 	 *
 	 * ARM code relies on the layout of the first 3 of these fields. Do not
 	 * change them.
 	 */
 
 	/**
-	 * The width of the surface.
+	 * Width of the surface.
 	 */
 	uint16 w;
 
 	/**
-	 * The height of the surface.
+	 * Height of the surface.
 	 */
 	uint16 h;
 
 	/**
-	 * The number of bytes a pixel line has.
+	 * Number of bytes in a pixel line.
 	 *
-	 * Note that this might not equal w * bytesPerPixel.
+	 * @note This might not equal w * bytesPerPixel.
 	 */
 	uint16 pitch;
 
 protected:
 	/**
-	 * The surface's pixel data.
+	 * Pixel data of the surface.
 	 */
 	void *pixels;
 
 public:
 	/**
-	 * The pixel format of the surface.
+	 * Pixel format of the surface.
 	 */
 	PixelFormat format;
 
@@ -101,9 +110,9 @@ public:
 	}
 
 	/**
-	 * Sets the pixel data.
+	 * Set the pixel data.
 	 *
-	 * Note that this is a simply a setter. Be careful what you are doing!
+	 * Note that this is a simply a setter. Be aware of that when using it.
 	 *
 	 * @param newPixels The new pixel data.
 	 */
@@ -112,8 +121,9 @@ public:
 	/**
 	 * 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.
+	 * @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 {
@@ -123,8 +133,9 @@ public:
 	/**
 	 * 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.
+	 * @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) {
@@ -134,223 +145,232 @@ public:
 	/**
 	 * Allocate memory for the pixel data of the surface.
 	 *
-	 * Note that you are responsible for calling free yourself.
-	 * @see free
+	 * The client code is responsible for calling @ref free.
 	 *
-	 * @param width Width of the surface object.
-	 * @param height Height of the surface object.
-	 * @param format The pixel format the surface should use.
+	 * @param width   Width of the surface object.
+	 * @param height  Height of the surface object.
+	 * @param format  The pixel format to be used by the surface.
 	 */
 	void create(uint16 width, uint16 height, const PixelFormat &format);
 
 	/**
-	 * Release the memory used by the pixels memory of this surface. This is the
-	 * counterpart to create().
+	 * Release the memory used by the pixel memory of this surface.
 	 *
-	 * Note that you should only use this, when you created the Surface data via
-	 * create! Otherwise this function has undefined behavior.
-	 * @see create
+	 * This is the counterpart of @ref create().
+	 *
+	 * @b Important: Only use this if you created the surface data using
+	 * @ref create. Otherwise, this function has undefined behavior.
 	 */
 	void free();
 
 	/**
-	 * Set up the Surface with user specified data.
+	 * Set up a surface with user-specified data.
 	 *
-	 * Note that this simply sets the 'internal' attributes of the Surface. It
-	 * will not take care of freeing old data via free or similar!
+	 * This simply sets the 'internal' attributes of the surface. It
+	 * does free old data using @ref free or similar methods.
 	 *
-	 * @param width Width of the pixel data.
-	 * @param height Height of the pixel data.
-	 * @param pitch The pitch of the pixel data.
-	 * @param pixels The pixel data itself.
-	 * @param format The pixel format of the pixel data.
+	 * @param width   Width of the pixel data.
+	 * @param height  Height of the pixel data.
+	 * @param pitch   Pitch of the pixel data.
+	 * @param pixels  Pixel data.
+	 * @param format  Pixel format of the pixel data.
 	 */
 	void init(uint16 width, uint16 height, uint16 pitch, void *pixels, const PixelFormat &format);
 
 	/**
-	 * Copy the data from another Surface.
+	 * 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
+	 * This calls @ref free on the current surface to assure that it is
+	 * clean. Make sure that the current data was created using @ref create.
+	 * Otherwise, the results are undefined.
 	 *
-	 * @param surf Surface to copy from.
+	 * @param surf  The surface to copy from.
 	 */
 	void copyFrom(const Surface &surf);
 
 	/**
-	 * Creates a Surface which represents a sub-area of this Surface object.
+	 * Create a surface that represents a sub-area of this Surface object.
 	 *
-	 * The pixel (0, 0) of the returned Surface will be the same as Pixel
-	 * (area.x, area.y) of this Surface. Changes to any of the Surface objects
-	 * will change the shared pixel data.
+	 * The pixel (0, 0) of the returned Surface will be the same as pixel
+	 * (area.x, area.y) of the parent surface. Changes to any of the parent surface
+	 * objects will change the shared pixel data.
 	 *
-	 * Note that the Surface returned is only valid as long as this Surface
-	 * object is still alive (i.e. its pixel data is not destroyed or
-	 * reallocated). Do *never* try to free the returned Surface.
+	 * The returned surface is only valid as long as this Surface
+	 * object still exists, that is, its pixel data is not destroyed or
+	 * reallocated.
 	 *
-	 * @param area The area which should be represented. Note that the area
-	 *             will get clipped in case it does not fit!
+	 * @b Important: Never attempt to free the returned surface.
+	 *
+	 * @param area  The area to be represented. Note that the area
+	 *              will get clipped in case it does not fit.
 	 */
 	Surface getSubArea(const Common::Rect &area);
 
 	/**
-	 * Creates a Surface which represents a sub-area of this Surface object.
+	 * Create a surface that represents a sub-area of this Surface object.
 	 *
-	 * The pixel (0, 0) of the returned Surface will be the same as Pixel
-	 * (area.x, area.y) of this Surface.
+	 * The pixel (0, 0) of the returned surface will be the same as pixel
+	 * (area.x, area.y) of the parent surface.
 	 *
-	 * Note that the Surface returned is only valid as long as this Surface
-	 * object is still alive (i.e. its pixel data is not destroyed or
-	 * reallocated). Do *never* try to free the returned Surface.
+	 * The returned surface is only valid as long as this Surface
+	 * object still exists, that is, its pixel data is not destroyed or
+	 * reallocated.
 	 *
-	 * @param area The area which should be represented. Note that the area
-	 *             will get clipped in case it does not fit!
+	 * @b Important: Never attempt to free the returned surface.
+	 *
+	 * @param area  The area to be represented. Note that the area
+	 *              will get clipped in case it does not fit.
 	 */
 	const Surface getSubArea(const Common::Rect &area) const;
 
 	/**
-	 * Copies a bitmap to the Surface internal buffer. The pixel format
-	 * of buffer must match the pixel format of the Surface.
+	 * Copy a bitmap to the internal buffer of the surface.
 	 *
-	 * @param buffer    The buffer containing the graphics data source
-	 * @param srcPitch     The pitch of the buffer (number of bytes in a scanline)
-	 * @param destX     The x coordinate of the destination rectangle
-	 * @param destY     The y coordinate of the destination rectangle
-	 * @param width     The width of the destination rectangle
-	 * @param height    The height of the destination rectangle
+	 * The pixel format of the buffer must match the pixel format of the surface.
+	 *
+	 * @param buffer    Buffer containing the graphics data source.
+	 * @param srcPitch  Pitch of the buffer (number of bytes in a scanline).
+	 * @param destX     The x coordinate of the destination rectangle.
+	 * @param destY     The y coordinate of the destination rectangle.
+	 * @param width     Width of the destination rectangle.
+	 * @param height    Height of the destination rectangle.
 	 */
 	void copyRectToSurface(const void *buffer, int srcPitch, int destX, int destY, int width, int height);
 	/**
-	 * Copies a bitmap to the Surface internal buffer. The pixel format
-	 * of buffer must match the pixel format of the Surface.
+	 * Copy a bitmap to the internal buffer of the surface.
 	 *
-	 * @param srcSurface    The source of the bitmap data
-	 * @param destX         The x coordinate of the destination rectangle
-	 * @param destY         The y coordinate of the destination rectangle
-	 * @param subRect       The subRect of surface to be blitted
+	 * The pixel format of the buffer must match the pixel format of the surface.
+	 *
+	 * @param srcSurface  Source of the bitmap data.
+	 * @param destX       The x coordinate of the destination rectangle.
+	 * @param destY       The y coordinate of the destination rectangle.
+	 * @param subRect     The subRect of the surface to be blitted.
 	 */
 	void copyRectToSurface(const Graphics::Surface &srcSurface, int destX, int destY, const Common::Rect subRect);
 
 	/**
 	 * Convert the data to another pixel format.
 	 *
-	 * This works in-place. This means it will not create an additional buffer
+	 * This works in-place. This means it does not create an additional buffer
 	 * for the conversion process. The value of 'pixels' might change though
 	 * (that means it might realloc the pixel data).
 	 *
-	 * Note that you should only use this, when you created the Surface data via
-	 * create! Otherwise this function has undefined behavior.
+	 * @b Important: Only use this if you created the surface data using
+	 * @ref create. Otherwise, this function has undefined behavior.
 	 *
-	 * @param dstFormat The desired format
-	 * @param palette   The palette (in RGB888), if the source format has a Bpp of 1
+	 * @param dstFormat  The desired format.
+	 * @param palette    The palette (in RGB888), if the source format has a bpp of 1.
 	 */
 	void convertToInPlace(const PixelFormat &dstFormat, const byte *palette = 0);
 
 	/**
 	 * Convert the data to another pixel format.
 	 *
-	 * The calling code must call free on the returned surface and then delete
+	 * The client code must call @ref free on the returned surface and then delete
 	 * it.
 	 *
-	 * @param dstFormat The desired format
-	 * @param palette   The palette (in RGB888), if the source format has a Bpp of 1
+	 * @param dstFormat  The desired format.
+	 * @param palette    The palette (in RGB888), if the source format has a bpp of 1.
 	 */
 	Graphics::Surface *convertTo(const PixelFormat &dstFormat, const byte *palette = 0) const;
 
 	/**
 	 * 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.
-	 * @note This is just a wrapper around Graphics::drawLine
+	 * @param x0     The x coordinate of the start point.
+	 * @param y0     The y coordinate of the start point.
+	 * @param x1     The x coordinate of the end point.
+	 * @param y1     The y coordinate of the end point.
+	 * @param color  Color of the line.
+	 *
+	 * @note This is just a wrapper around Graphics::drawLine.
 	 */
 	void drawLine(int x0, int y0, int x1, int y1, uint32 color);
 
 	/**
 	 * Draw a thick 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 penX The width of the pen (thickness in the x direction)
-	 * @param penY The height of the pen (thickness in the y direction)
-	 * @param color The color of the line.
-	 * @note This is just a wrapper around Graphics::drawThickLine
-	 * @note The x/y coordinates of the start and end points are the upper-left most part of the pen
+	 * @param x0     The x coordinate of the start point.
+	 * @param y0     The y coordinate of the start point.
+	 * @param x1     The x coordinate of the end point.
+	 * @param y1     The y coordinate of the end point.
+	 * @param penX   Width of the pen (thickness in the x direction).
+	 * @param penY   Height of the pen (thickness in the y direction).
+	 * @param color  Color of the line.
+	 *
+	 * @note This is just a wrapper around Graphics::drawThickLine.
+	 *
+	 * @note The x/y coordinates of the start and end points are the upper leftmost part of the pen.
 	 */
 	void drawThickLine(int x0, int y0, int x1, int y1, int penX, int penY, 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.
+	 * @param x      The start x coordinate of the line.
+	 * @param y      The y coordinate of the line.
+	 * @param x2     The end x coordinate of the line.
+	 *               In case x > x2, the coordinates are swapped.
+	 * @param color  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.
+	 * @param x      The x coordinate of the line.
+	 * @param y      The start y coordinate of the line.
+	 * @param y2     The end y coordinate of the line.
+	 *               In case y > y2, the coordinates are swapped.
+	 * @param color  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.
+	 * @param r      The rectangle to fill.
+	 * @param color  The color to fill the rect with.
 	 */
 	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.
+	 * @param r      The rectangle 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
+	/**
+	 * Move the content of the surface horizontally or vertically
+	 * by the given number of pixels.
+	 */
 	void move(int dx, int dy, int height);
 
 	/**
 	 * Flip the specified rect vertically.
 	 *
-	 * @param r Rect to flip
+	 * @param r  The rectangle to flip.
 	 */
 	void flipVertical(const Common::Rect &r);
 
 	/**
 	 * Scale the data to the given size.
 	 *
-	 * The calling code must call free on the returned surface and then delete
+	 * The client code must call @ref free on the returned surface and then delete
 	 * it.
 	 *
-	 * @param newWidth the resulting width.
-	 * @param newHeight the resulting height.
-	 * @param filtering Whether or not to use bilinear filtering.
+	 * @param newWidth   The resulting width.
+	 * @param newHeight  The resulting height.
+	 * @param filtering  Whether or not to use bilinear filtering.
 	 */
 	Graphics::Surface *scale(uint16 newWidth, uint16 newHeight, bool filtering = false) const;
 
 };
 
 /**
- * A deleter for Surface objects which can be used with SharedPtr.
+ * A deleter for Surface objects that can be used with SharedPtr.
  *
  * This deleter assures Surface::free is called on deletion.
  */
@@ -364,23 +384,23 @@ struct SurfaceDeleter {
 };
 
 /**
- * Stack-based flood fill algorithm for arbitrary Surfaces.
+ * Stack-based flood fill algorithm for arbitrary surfaces.
  *
- * It could be used in 2 ways. One is to fill the pixels of oldColor
+ * This can be used in two ways. One is to fill the pixels of oldColor
  * with fillColor. Second is when the surface stays intact but another
  * surface with mask is created, where filled colors are marked with 255.
  *
  * Before running fill() or fillMask(), the initial pixels must be addSeed
- * with addSeed() method.
+ * with the addSeed() method.
  */
 class FloodFill {
 public:
 	/**
 	 * Construct a simple Surface object.
 	 *
-	 * @param surface Input surface
-	 * @param oldColor Color on the surface to change
-	 * @param fillColor Color to fill with
+	 * @param surface    Input surface.
+	 * @param oldColor   The color on the surface to change.
+	 * @param fillColor  The color to fill with.
 	 */
 	FloodFill(Surface *surface, uint32 oldColor, uint32 fillColor, bool maskMode = false);
 	~FloodFill();
@@ -388,27 +408,25 @@ public:
 	/**
 	 * Add pixels to the fill queue.
 	 *
-	 * @param x The x coordinate of the pixel.
-	 * @param y The x coordinate of the pixel.
+	 * @param x  The x coordinate of the pixel.
+	 * @param y  The x coordinate of the pixel.
 	 */
 	void addSeed(int x, int y);
 
 	/**
 	 * Fill the surface as requested.
 	 *
-	 * It uses pixels which were added with addSeed() method.
-	 *
-	 * @see addSeed
+	 * This uses pixels that were added with the @ref addSeed() method.
 	 */
 	void fill();
 
 	/**
-	 * Fill the mask. The mask is a CLUT8 Surface with pixels 0 and 255.
+	 * Fill the mask.
+	 *
+	 * The mask is a CLUT8 surface with pixels 0 and 255.
 	 * 255 means that the pixel has been filled.
 	 *
-	 * It uses pixels which were added with addSeed() method.
-	 *
-	 * @see addSeed
+	 * This uses pixels that were added with the @ref addSeed() method.
 	 */
 	void fillMask();
 
@@ -429,7 +447,7 @@ private:
 
 	bool _maskMode;
 };
-
+/** @} */
 } // End of namespace Graphics