From fd2a120c9d97e148452ccf50fd1186f3773abbe1 Mon Sep 17 00:00:00 2001
From: TechGeekNZ <git@tech.geek.nz>
Date: Wed, 17 Jun 2020 12:07:28 +1200
Subject: [PATCH] Cleanup: Improve documentation of dirty block system.

Partially re-applies 8652a4db76c978598918bfdb600a3453d794930a, which
was reverted to allow commits to be cherry-picked from JGRPP.
---
 src/gfx.cpp | 22 ++++++++++++++++------
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/src/gfx.cpp b/src/gfx.cpp
index a5e5772050..15653c0c48 100644
--- a/src/gfx.cpp
+++ b/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
- * now contains the rectangle defined by the given parameters. Note
- * the point (0,0) is top left.
+ * Add the specified rectangle to the collection of screen areas to be
+ * invalidated and redrawn.
+ * 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
- *       it neither set a dirty rect nor add several dirty rects although
- *       the function name is in plural. (Progman)
+ * @ingroup dirty
  */
 void SetDirtyBlocks(int left, int top, int right, int bottom)
 {