Cleanup: Improve documentation of dirty block system.

Partially re-applies 8652a4db76, which
was reverted to allow commits to be cherry-picked from JGRPP.

src/gfx.cpp

@@ -1416,6 +1416,16 @@ void DrawMouseCursor()
 	_cursor.dirty = false;
 }
 
+/**
+ * Repaints a specific rectangle of the screen.
+ *
+ * @param left,top,right,bottom The area of the screen that needs repainting
+ * @pre The rectangle is assumed to have been previously marked dirty with \c SetDirtyBlocks.
+ * @see SetDirtyBlocks
+ * @see DrawDirtyBlocks
+ * @ingroup dirty
+ *
+ */
 void RedrawScreenRect(int left, int top, int right, int bottom)
 {
 	assert(right <= _screen.width && bottom <= _screen.height);
@@ -1439,6 +1449,8 @@ void RedrawScreenRect(int left, int top, int right, int bottom)
  * Repaints the rectangle blocks which are marked as 'dirty'.
  *
  * @see SetDirtyBlocks
+ *
+ * @ingroup dirty
  */
 void DrawDirtyBlocks()
 {
@@ -1541,9 +1553,9 @@ void DrawDirtyBlocks()
 }
 
 /**
- * This function extends the internal _invalid_rect rectangle as it
+ * Add the specified rectangle to the collection of screen areas to be
- * now contains the rectangle defined by the given parameters. Note
+ * invalidated and redrawn.
- * the point (0,0) is top left.
+ * Note the point (0,0) is top left.
  *
  * @param left The left edge of the rectangle
  * @param top The top edge of the rectangle
@@ -1551,9 +1563,7 @@ void DrawDirtyBlocks()
  * @param bottom The bottom edge of the rectangle
  * @see DrawDirtyBlocks
  *
- * @todo The name of the function should be called like @c AddDirtyBlock as
+ * @ingroup dirty
- *       it neither set a dirty rect nor add several dirty rects although
- *       the function name is in plural. (Progman)
  */
 void SetDirtyBlocks(int left, int top, int right, int bottom)
 {