From f1616060e52325796b52c87931ecc6b79ab72545 Mon Sep 17 00:00:00 2001
From: Anders Jenbo <anders@jenbo.dk>
Date: Sat, 15 Feb 2020 04:26:51 +0100
Subject: [PATCH 1/4] Document CL2 render functions

---
 Source/control.cpp  |  12 ++---
 Source/engine.cpp   | 112 ++++++++++++++++++++++++++++++++++++++++++++
 Source/lighting.cpp |  56 ++++++++++++----------
 Source/scrollrt.cpp |  86 +++++++++++++++++-----------------
 4 files changed, 193 insertions(+), 73 deletions(-)

diff --git a/Source/control.cpp b/Source/control.cpp
index 881197b3d..5a1747fef 100644
--- a/Source/control.cpp
+++ b/Source/control.cpp
@@ -216,8 +216,8 @@ int SpellPages[6][7] = {
 
 /**
  * Draw spell cell onto the back buffer.
- * @param xp Backbuffer coordinate
- * @param yp Backbuffer coordinate
+ * @param xp Back buffer coordinate
+ * @param yp Back buffer coordinate
  * @param Trans Pointer to the cel buffer.
  * @param nCel Index of the cel frame to draw. 0 based.
  * @param w Width of the frame.
@@ -614,8 +614,8 @@ void ToggleSpell(int slot)
 }
 
 /**
- * @brief Print letter to the backbuffer
- * @param nOffset Backbuffer offset
+ * @brief Print letter to the back buffer
+ * @param nOffset Back buffer offset
  * @param nCel Number of letter in Windows-1252
  * @param col text_color color value
  */
@@ -1006,8 +1006,8 @@ void DrawPanelBox(int x, int y, int w, int h, int sx, int sy)
  * @param pCelBuff Buffer of the empty flask cel.
  * @param min Top of the flask cel section to draw.
  * @param max Bottom of the flask cel section to draw.
- * @param sx X Backbuffer coordinate
- * @param sy Y Backbuffer coordinate
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
  */
 void SetFlaskHeight(BYTE *pCelBuff, int min, int max, int sx, int sy)
 {
diff --git a/Source/engine.cpp b/Source/engine.cpp
index 2278ccdb2..e45e487c9 100644
--- a/Source/engine.cpp
+++ b/Source/engine.cpp
@@ -16,7 +16,14 @@ static CCritSect sgMemCrit;
 int SeedCount;
 BOOL gbNotInView; // valid - if x/y are in bounds
 
+/**
+ * Specifies the increment used in the Borland C/C++ pseudo-random.
+ */
 const int RndInc = 1;
+
+/**
+ * Specifies the multiplier used in the Borland C/C++ pseudo-random number generator algorithm.
+ */
 const int RndMult = 0x015A4E35;
 
 __FINLINE BYTE *CelGetFrame(BYTE *pCelBuff, int nCel, int *nDataSize)
@@ -2467,6 +2474,9 @@ DWORD LoadFileWithMem(const char *pszName, void *p)
 
 /**
  * @brief Apply the color swaps to a CL2 sprite
+ * @param p CL2 buffer
+ * @param ttbl Palette translation table
+ * @param nCel Frame number in CL2 file
  */
 void Cl2ApplyTrans(BYTE *p, BYTE *ttbl, int nCel)
 {
@@ -2508,6 +2518,12 @@ void Cl2ApplyTrans(BYTE *p, BYTE *ttbl, int nCel)
 }
 
 /**
+ * @brief Blit CL2 sprite, to the back buffer at the given coordianates
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
+ * @param pCelBuff CL2 buffer
+ * @param nCel CL2 frame number
+ * @param nWidth Width of sprite
  * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8
  * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8
  */
@@ -2548,6 +2564,13 @@ void Cl2Draw(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, int CelSkip,
 	    nWidth);
 }
 
+/**
+ * @brief Blit CL2 sprite to the given buffer
+ * @param pDecodeTo The output buffer
+ * @param pRLEBytes CL2 pixel stream (run-length encoded)
+ * @param nDataSize Size of CL2 in bytes
+ * @param nWidth Width of sprite
+ */
 void Cl2Blit(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth)
 {
 #ifdef USE_ASM
@@ -2690,6 +2713,13 @@ void Cl2Blit(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth)
 }
 
 /**
+ * @brief Blit a solid colder shape one pix larger then the given sprite shape, to the back buffer at the given coordianates
+ * @param col Color index from current palette
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
+ * @param pCelBuff CL2 buffer
+ * @param nCel CL2 frame number
+ * @param nWidth Width of sprite
  * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8
  * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8
  */
@@ -2731,6 +2761,14 @@ void Cl2DrawOutline(char col, int sx, int sy, BYTE *pCelBuff, int nCel, int nWid
 	    col);
 }
 
+/**
+ * @brief Blit a solid colder shape one pix larger then the given sprite shape, to the given buffer
+ * @param pDecodeTo The output buffer
+ * @param pRLEBytes CL2 pixel stream (run-length encoded)
+ * @param nDataSize Size of CL2 in bytes
+ * @param nWidth Width of sprite
+ * @param col Color index from current palette
+ */
 void Cl2BlitOutline(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth, char col)
 {
 #ifdef USE_ASM
@@ -2894,8 +2932,15 @@ void Cl2BlitOutline(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth,
 }
 
 /**
+ * @brief Blit CL2 sprite, and apply a given lighting, to the back buffer at the given coordianates
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
+ * @param pCelBuff CL2 buffer
+ * @param nCel CL2 frame number
+ * @param nWidth Width of sprite
  * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8
  * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8
+ * @param light Light shade to use
  */
 void Cl2DrawLightTbl(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, int CelSkip, int CelCap, char light)
 {
@@ -2945,6 +2990,14 @@ void Cl2DrawLightTbl(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, int C
 	    &pLightTbl[idx]);
 }
 
+/**
+ * @brief Blit CL2 sprite, and apply lighting, to the given buffer
+ * @param pDecodeTo The output buffer
+ * @param pRLEBytes CL2 pixel stream (run-length encoded)
+ * @param nDataSize Size of CL2 in bytes
+ * @param nWidth Width of sprite
+ * @param pTable Light color table
+ */
 void Cl2BlitLight(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth, BYTE *pTable)
 {
 #ifdef USE_ASM
@@ -3096,6 +3149,12 @@ void Cl2BlitLight(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth, B
 }
 
 /**
+ * @brief Blit CL2 sprite, and apply lighting, to the back buffer at the given coordinates
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
+ * @param pCelBuff CL2 buffer
+ * @param nCel CL2 frame number
+ * @param nWidth Width of sprite
  * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8
  * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8
  */
@@ -3140,6 +3199,12 @@ void Cl2DrawLight(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, int CelS
 }
 
 /**
+ * @brief Blit CL2 sprite to the back buffer, while checking bounds, at the given coordianates
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
+ * @param pCelBuff CL2 buffer
+ * @param nCel CL2 frame number
+ * @param nWidth Width of sprite
  * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8
  * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8
  */
@@ -3180,6 +3245,13 @@ void Cl2DrawSafe(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, int CelSk
 	    nWidth);
 }
 
+/**
+ * @brief Blit CL2 sprite to pDecodeTo while checking bounds
+ * @param pDecodeTo The output buffer
+ * @param pRLEBytes CL2 pixel stream (run-length encoded)
+ * @param nDataSize Size of CL2 in bytes
+ * @param nWidth Width of sprite
+ */
 void Cl2BlitSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth)
 {
 #ifdef USE_ASM
@@ -3335,6 +3407,13 @@ void Cl2BlitSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth)
 }
 
 /**
+ * @brief Blit a solid colder shape one pix larger then the given sprite shape, to the back buffer at the given coordianates, while checking bounds
+ * @param col Color index from current palette
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
+ * @param pCelBuff CL2 buffer
+ * @param nCel CL2 frame number
+ * @param nWidth Width of sprite
  * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8
  * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8
  */
@@ -3378,6 +3457,14 @@ void Cl2DrawOutlineSafe(char col, int sx, int sy, BYTE *pCelBuff, int nCel, int
 	gpBufEnd += BUFFER_WIDTH;
 }
 
+/**
+ * @brief Blit a solid colder shape one pix larger then the given sprite shape, to the given buffer, while checking bounds
+ * @param pDecodeTo The output buffer
+ * @param pRLEBytes CL2 pixel stream (run-length encoded)
+ * @param nDataSize Size of CL2 in bytes
+ * @param nWidth Width of sprite
+ * @param col Color index from current palette
+ */
 void Cl2BlitOutlineSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth, char col)
 {
 #ifdef USE_ASM
@@ -3552,8 +3639,15 @@ void Cl2BlitOutlineSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWi
 }
 
 /**
+ * @brief Blit CL2 sprite, and apply a given lighting, to the back buffer at the given coordianates, while checking bounds
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
+ * @param pCelBuff CL2 buffer
+ * @param nCel CL2 frame number
+ * @param nWidth Width of sprite
  * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8
  * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8
+ * @param light light shade to use
  */
 void Cl2DrawLightTblSafe(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, int CelSkip, int CelCap, char light)
 {
@@ -3603,6 +3697,14 @@ void Cl2DrawLightTblSafe(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, i
 	    &pLightTbl[idx]);
 }
 
+/**
+ * @brief Blit CL2 sprite, and apply light, to pDecodeTo while checking bounds
+ * @param pDecodeTo The output buffer
+ * @param pRLEBytes CL2 pixel stream (run-length encoded)
+ * @param nDataSize Size of CL2 in bytes
+ * @param nWidth With of CL2 sprite
+ * @param pTable Light color table
+ */
 void Cl2BlitLightSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth, BYTE *pTable)
 {
 #ifdef USE_ASM
@@ -3767,6 +3869,12 @@ void Cl2BlitLightSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidt
 }
 
 /**
+ * @brief Blit CL2 sprite, and apply lighting, to the back buffer at the given coordinates, while checking bounds
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
+ * @param pCelBuff CL2 buffer
+ * @param nCel CL2 frame number
+ * @param nWidth Width of sprite
  * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8
  * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8
  */
@@ -3810,6 +3918,10 @@ void Cl2DrawLightSafe(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, int
 		Cl2BlitSafe(pDecodeTo, pRLEBytes, nSize, nWidth);
 }
 
+/**
+ * @brief Fade to black and play a video
+ * @param pszMovie file path of movie
+ */
 void PlayInGameMovie(char *pszMovie)
 {
 	PaletteFadeOut(8);
diff --git a/Source/lighting.cpp b/Source/lighting.cpp
index 5343d3c6a..51b8edaaa 100644
--- a/Source/lighting.cpp
+++ b/Source/lighting.cpp
@@ -14,28 +14,29 @@ int visionid;
 BYTE *pLightTbl;
 BOOL lightflag;
 
-// CrawlTable specifies X- and Y-coordinate deltas from a missile target
-// coordinate.
-//
-// n=4
-//
-//    y
-//    ^
-//    |  1
-//    | 3#4
-//    |  2
-//    +-----> x
-//
-// n=16
-//
-//    y
-//    ^
-//    |  314
-//    | B7 8C
-//    | F # G
-//    | D9 AE
-//    |  526
-//    +-------> x
+/**
+ * CrawlTable specifies X- and Y-coordinate deltas from a missile target coordinate.
+ *
+ * n=4
+ *
+ *    y
+ *    ^
+ *    |  1
+ *    | 3#4
+ *    |  2
+ *    +-----> x
+ *
+ * n=16
+ *
+ *    y
+ *    ^
+ *    |  314
+ *    | B7 8C
+ *    | F # G
+ *    | D9 AE
+ *    |  526
+ *    +-------> x
+ */
 char CrawlTable[2749] = {
 	1,
 	0, 0,
@@ -400,8 +401,9 @@ char CrawlTable[2749] = {
 	-18, -1, 18, -1, -18, 0, 18, 0
 };
 
-// pCrawlTable maps from circle radius to the X- and Y-coordinate deltas from
-// the center of a circle.
+/**
+ * pCrawlTable maps from circle radius to the X- and Y-coordinate deltas from the center of a circle.
+ */
 char *pCrawlTable[19] = {
 	CrawlTable,
 	CrawlTable + 3,
@@ -423,6 +425,9 @@ char *pCrawlTable[19] = {
 	CrawlTable + 2187,
 	CrawlTable + 2460
 };
+/**
+ * vCrawlTable specifies the X- Y-coordinate offsets of lighting visions.
+ */
 BYTE vCrawlTable[23][30] = {
 	{ 1, 0, 2, 0, 3, 0, 4, 0, 5, 0, 6, 0, 7, 0, 8, 0, 9, 0, 10, 0, 11, 0, 12, 0, 13, 0, 14, 0, 15, 0 },
 	{ 1, 0, 2, 0, 3, 0, 4, 0, 5, 0, 6, 0, 7, 0, 8, 1, 9, 1, 10, 1, 11, 1, 12, 1, 13, 1, 14, 1, 15, 1 },
@@ -470,6 +475,9 @@ BYTE byte_49463C[18][18] = /* unused */
 	    { 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2 }
     };
 
+/**
+ * RadiusAdj maps from vCrawlTable index to lighting vision radius adjustment.
+ */
 BYTE RadiusAdj[23] = { 0, 0, 0, 0, 1, 1, 1, 2, 2, 2, 3, 4, 3, 2, 2, 2, 1, 1, 1, 0, 0, 0, 0 };
 
 void RotateRadius(int *x, int *y, int *dx, int *dy, int *lx, int *ly, int *bx, int *by)
diff --git a/Source/scrollrt.cpp b/Source/scrollrt.cpp
index 4bd011598..92c5d8e4e 100644
--- a/Source/scrollrt.cpp
+++ b/Source/scrollrt.cpp
@@ -67,7 +67,7 @@ void ClearCursor() // CODE_FIX: this was supposed to be in cursor.cpp
 }
 
 /**
- * @brief Remove the cursor from the backbuffer
+ * @brief Remove the cursor from the back buffer
  */
 static void scrollrt_draw_cursor_back_buffer()
 {
@@ -99,7 +99,7 @@ static void scrollrt_draw_cursor_back_buffer()
 }
 
 /**
- * @brief Draw the cursor on the backbuffer
+ * @brief Draw the cursor on the back buffer
  */
 static void scrollrt_draw_cursor_item()
 {
@@ -179,8 +179,8 @@ static void scrollrt_draw_cursor_item()
  * @brief Render a missile sprite
  * @param x dPiece coordinate
  * @param y dPiece coordinate
- * @param sx Backbuffer coordinate
- * @param sy Backbuffer coordinate
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
  * @param CelSkip Skip part of sprite, see Cl2Draw
  * @param CelCap  Skip part of sprite, see Cl2Draw
  * @param pre Is the sprite in the background
@@ -250,8 +250,8 @@ void DrawMissile(int x, int y, int sx, int sy, int CelSkip, int CelCap, BOOL pre
  * @brief Render a missile sprite, check for overdraw on lower screen
  * @param x dPiece coordinate
  * @param y dPiece coordinate
- * @param sx Backbuffer coordinate
- * @param sy Backbuffer coordinate
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
  * @param CelSkip Skip part of sprite, see Cl2Draw
  * @param CelCap  Skip part of sprite, see Cl2Draw
  * @param pre Is the sprite in the background
@@ -321,8 +321,8 @@ void DrawClippedMissile(int x, int y, int sx, int sy, int CelSkip, int CelCap, B
  * @brief Render a monster sprite
  * @param x dPiece coordinate
  * @param y dPiece coordinate
- * @param mx Backbuffer coordinate
- * @param my Backbuffer coordinate
+ * @param mx Back buffer coordinate
+ * @param my Back buffer coordinate
  * @param CelSkip Skip part of sprite, see Cl2Draw
  * @param CelCap  Skip part of sprite, see Cl2Draw
  */
@@ -383,8 +383,8 @@ static void DrawMonster(int x, int y, int mx, int my, int m, int CelSkip, int Ce
  * @brief Render a monster sprite, check for overdraw on lower screen
  * @param x dPiece coordinate
  * @param y dPiece coordinate
- * @param mx Backbuffer coordinate
- * @param my Backbuffer coordinate
+ * @param mx Back buffer coordinate
+ * @param my Back buffer coordinate
  * @param CelSkip Skip part of sprite, see Cl2Draw
  * @param CelCap  Skip part of sprite, see Cl2Draw
  */
@@ -446,8 +446,8 @@ static void DrawClippedMonster(int x, int y, int mx, int my, int m, int CelSkip,
  * @param pnum Player id
  * @param x dPiece coordinate
  * @param y dPiece coordinate
- * @param px Backbuffer coordinate
- * @param py Backbuffer coordinate
+ * @param px Back buffer coordinate
+ * @param py Back buffer coordinate
  * @param pCelBuff sprite buffer
  * @param nCel frame
  * @param nWidth width
@@ -532,8 +532,8 @@ static void DrawPlayer(int pnum, int x, int y, int px, int py, BYTE *pCelBuff, i
  * @param pnum Player id
  * @param x dPiece coordinate
  * @param y dPiece coordinate
- * @param px Backbuffer coordinate
- * @param py Backbuffer coordinate
+ * @param px Back buffer coordinate
+ * @param py Back buffer coordinate
  * @param pCelBuff sprite buffer
  * @param nCel frame
  * @param nWidth width
@@ -617,8 +617,8 @@ static void DrawClippedPlayer(int pnum, int x, int y, int px, int py, BYTE *pCel
  * @brief Render a monster sprite
  * @param x dPiece coordinate
  * @param y dPiece coordinate
- * @param sx Backbuffer coordinate
- * @param sy Backbuffer coordinate
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
  * @param CelSkip Skip part of sprite, see Cl2Draw
  * @param CelCap  Skip part of sprite, see Cl2Draw
  * @param clipped check for overdraw on lower screen
@@ -663,8 +663,8 @@ void DrawDeadPlayer(int x, int y, int sx, int sy, int CelSkip, int CelCap, BOOL
  * @brief Render an object sprite
  * @param x dPiece coordinate
  * @param y dPiece coordinate
- * @param ox Backbuffer coordinate
- * @param oy Backbuffer coordinate
+ * @param ox Back buffer coordinate
+ * @param oy Back buffer coordinate
  * @param pre Is the sprite in the background
  * @param CelSkip Skip part of sprite, see Cl2Draw
  * @param CelCap  Skip part of sprite, see Cl2Draw
@@ -726,8 +726,8 @@ static void DrawObject(int x, int y, int ox, int oy, BOOL pre, int CelSkip, int
  * @brief Render an object sprite, check for overdraw on lower screen
  * @param x dPiece coordinate
  * @param y dPiece coordinate
- * @param ox Backbuffer coordinate
- * @param oy Backbuffer coordinate
+ * @param ox Back buffer coordinate
+ * @param oy Back buffer coordinate
  * @param pre Is the sprite in the background
  * @param CelSkip Skip part of sprite, see Cl2Draw
  * @param CelCap  Skip part of sprite, see Cl2Draw
@@ -791,8 +791,8 @@ static void scrollrt_draw_clipped_dungeon(BYTE *pBuff, int sx, int sy, int dx, i
  * @param pBuff Pointer to output buffer at location sx,sy
  * @param y dPiece coordinate
  * @param x dPiece coordinate
- * @param sx Backbuffer coordinate
- * @param sy Backbuffer coordinate
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
  */
 static void scrollrt_draw_clipped_e_flag(BYTE *pBuff, int x, int y, int sx, int sy)
 {
@@ -847,8 +847,8 @@ static void scrollrt_draw_clipped_e_flag(BYTE *pBuff, int x, int y, int sx, int
  * @param pBuff where to render to with sx,sy already applied
  * @param sx dPiece coordinate
  * @param sy dPiece coordinate
- * @param dx Backbuffer coordinate
- * @param dy Backbuffer coordinate
+ * @param dx Back buffer coordinate
+ * @param dy Back buffer coordinate
  * @param eflag Should the sorting workaround be applied
  */
 static void scrollrt_draw_clipped_dungeon(BYTE *pBuff, int sx, int sy, int dx, int dy, int eflag)
@@ -1069,8 +1069,8 @@ static void scrollrt_draw_clipped_dungeon(BYTE *pBuff, int sx, int sy, int dx, i
  * @brief Render a row of tile
  * @param x dPiece coordinate
  * @param y dPiece coordinate
- * @param sx Backbuffer coordinate
- * @param sy Backbuffer coordinate
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
  * @param chunks tile width of row
  * @param eflag is it an even (0) or odd (1) row
  */
@@ -1233,8 +1233,8 @@ static void scrollrt_draw_clipped_dungeon_2(BYTE *pBuff, int sx, int sy, int row
  * @param x dPiece coordinate
  * @param row The current row being rendered
  * @param CelSkip chunks of cell to skip
- * @param sx Backbuffer coordinate
- * @param sy Backbuffer coordinate
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
  */
 static void scrollrt_draw_clipped_e_flag_2(BYTE *pBuff, int x, int y, int row, int CelSkip, int sx, int sy)
 {
@@ -1312,8 +1312,8 @@ static void scrollrt_draw_clipped_e_flag_2(BYTE *pBuff, int x, int y, int row, i
  * @param sy dPiece coordinate
  * @param row The current row being rendered
  * @param CelSkip chunks of cell to skip
- * @param dx Backbuffer coordinate
- * @param dy Backbuffer coordinate
+ * @param dx Back buffer coordinate
+ * @param dy Back buffer coordinate
  * @param eflag Should the sorting workaround be applied
  */
 static void scrollrt_draw_clipped_dungeon_2(BYTE *pBuff, int sx, int sy, int row, int CelSkip, int dx, int dy, int eflag)
@@ -1534,8 +1534,8 @@ static void scrollrt_draw_clipped_dungeon_2(BYTE *pBuff, int sx, int sy, int row
  * @brief Render a row of tile, checking for overdrawing on lower part of screen
  * @param x dPiece coordinate
  * @param y dPiece coordinate
- * @param sx Backbuffer coordinate
- * @param sy Backbuffer coordinate
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
  * @param chunks tile width of row
  * @param row current row being rendered
  * @param eflag is it an even (0) or odd (1) row
@@ -1651,8 +1651,8 @@ static void scrollrt_draw_dungeon(BYTE *pBuff, int sx, int sy, int row, int CelC
  * @param x dPiece coordinate
  * @param row The current row being rendered
  * @param CelCap chunks of cell to skip
- * @param sx Backbuffer coordinate
- * @param sy Backbuffer coordinate
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
  */
 static void scrollrt_draw_e_flag(BYTE *pBuff, int x, int y, int row, int CelCap, int sx, int sy)
 {
@@ -1710,8 +1710,8 @@ static void scrollrt_draw_e_flag(BYTE *pBuff, int x, int y, int row, int CelCap,
  * @param sy dPiece coordinate
  * @param row The current row being rendered
  * @param CelCap chunks of cell to skip
- * @param dx Backbuffer coordinate
- * @param dy Backbuffer coordinate
+ * @param dx Back buffer coordinate
+ * @param dy Back buffer coordinate
  * @param eflag Should the sorting workaround be applied
  */
 static void scrollrt_draw_dungeon(BYTE *pBuff, int sx, int sy, int row, int CelCap, int dx, int dy, int eflag)
@@ -1922,8 +1922,8 @@ static void scrollrt_draw_dungeon(BYTE *pBuff, int sx, int sy, int row, int CelC
  * @brief Render a row of tile, checking for overdrawing on upper part of screen
  * @param x dPiece coordinate
  * @param y dPiece coordinate
- * @param sx Backbuffer coordinate
- * @param sy Backbuffer coordinate
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
  * @param chunks tile width of row
  * @param row current row being rendered
  * @param eflag is it an even (0) or odd (1) row
@@ -2569,11 +2569,11 @@ static void DrawFPS()
 #endif
 
 /**
- * @brief Update part of the screen from the backbuffer
- * @param dwX Backbuffer coordinate
- * @param dwY Backbuffer coordinate
- * @param dwWdt Backbuffer coordinate
- * @param dwHgt Backbuffer coordinate
+ * @brief Update part of the screen from the back buffer
+ * @param dwX Back buffer coordinate
+ * @param dwY Back buffer coordinate
+ * @param dwWdt Back buffer coordinate
+ * @param dwHgt Back buffer coordinate
  */
 static void DoBlitScreen(DWORD dwX, DWORD dwY, DWORD dwWdt, DWORD dwHgt)
 {

From a29d64b923f5fdc9266ebe4bffb817743d2b71a7 Mon Sep 17 00:00:00 2001
From: Anders Jenbo <anders@jenbo.dk>
Date: Sat, 15 Feb 2020 18:40:58 +0100
Subject: [PATCH 2/4] Document engine.cpp functions

---
 Source/engine.cpp | 241 +++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 219 insertions(+), 22 deletions(-)

diff --git a/Source/engine.cpp b/Source/engine.cpp
index e45e487c9..5836aafa6 100644
--- a/Source/engine.cpp
+++ b/Source/engine.cpp
@@ -26,6 +26,12 @@ const int RndInc = 1;
  */
 const int RndMult = 0x015A4E35;
 
+/**
+ * @brief Find the start of a CEL frame
+ * @param pCelBuff Cel data
+ * @param nCel CEL frame number
+ * @param nDataSize Will be set to frame size
+ */
 __FINLINE BYTE *CelGetFrame(BYTE *pCelBuff, int nCel, int *nDataSize)
 {
 	DWORD *pFrameTable;
@@ -38,6 +44,12 @@ __FINLINE BYTE *CelGetFrame(BYTE *pCelBuff, int nCel, int *nDataSize)
 	return pCelBuff + nCellStart;
 }
 
+/**
+ * @brief Calculate the size of a CEL frame
+ * @param pCelBuff Cel data
+ * @param nCel CEL frame number
+ * @return Size of CEL in bytes
+ */
 __FINLINE int CelGetFrameSize(BYTE *pCelBuff, int nCel)
 {
 	DWORD *pFrameTable;
@@ -47,6 +59,13 @@ __FINLINE int CelGetFrameSize(BYTE *pCelBuff, int nCel)
 	return SwapLE32(pFrameTable[nCel + 1]) - SwapLE32(pFrameTable[nCel]);
 }
 
+/**
+ * @brief Blit CEL sprite to the given buffer
+ * @param pDecodeTo The output buffer
+ * @param pRLEBytes CEL pixel stream (run-length encoded)
+ * @param nDataSize Size of CEL in bytes
+ * @param nWidth Width of sprite
+ */
 void CelBlit(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth)
 {
 	int w;
@@ -146,6 +165,14 @@ void CelBlit(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth)
 #endif
 }
 
+/**
+ * @brief Blit CEL sprite to the back buffer at the given coordinates
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
+ * @param pCelBuff Cel data
+ * @param nCel CEL frame number
+ * @param nWidth Width of sprite
+ */
 void CelDraw(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth)
 {
 	int nDataSize;
@@ -162,6 +189,13 @@ void CelDraw(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth)
 	CelBlit(&gpBuffer[sx + PitchTbl[sy]], pRLEBytes, nDataSize, nWidth);
 }
 
+/**
+ * @brief Blit a given CEL frame to the given buffer
+ * @param pBuff Target buffer
+ * @param pCelBuff Cel data
+ * @param nCel CEL frame number
+ * @param nWidth Width of sprite
+ */
 void CelBlitFrame(BYTE *pBuff, BYTE *pCelBuff, int nCel, int nWidth)
 {
 	int nDataSize;
@@ -179,6 +213,12 @@ void CelBlitFrame(BYTE *pBuff, BYTE *pCelBuff, int nCel, int nWidth)
 }
 
 /**
+ * @brief Same as CelDraw but with the option to skip parts of the top and bottom of the sprite
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
+ * @param pCelBuff Cel data
+ * @param nCel CEL frame number
+ * @param nWidth Width of sprite
  * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8
  * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8
  */
@@ -220,6 +260,11 @@ void CelClippedDraw(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, int Ce
 }
 
 /**
+ * @brief Same as CelBlit but with the option to skip parts of the top and bottom of the sprite
+ * @param pBuff Target buffer
+ * @param pCelBuff Cel data
+ * @param nCel CEL frame number
+ * @param nWidth Width of sprite
  * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8
  * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8
  */
@@ -256,6 +301,13 @@ void CelClippedBlit(BYTE *pBuff, BYTE *pCelBuff, int nCel, int nWidth, int CelSk
 	CelBlit(pBuff, pRLEBytes + nDataStart, nDataSize, nWidth);
 }
 
+/**
+ * @brief Blit CEL sprite, and apply lighting, to the given buffer
+ * @param pDecodeTo The output buffer
+ * @param pRLEBytes CEL pixel stream (run-length encoded)
+ * @param nDataSize Size of CEL in bytes
+ * @param nWidth Width of sprite
+ */
 void CelBlitLight(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth)
 {
 	int w;
@@ -409,6 +461,13 @@ void CelBlitLight(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth)
 #endif
 }
 
+/**
+ * @brief Blit CEL sprite, and apply lighting, to the given buffer, with transparancy applied
+ * @param pDecodeTo The output buffer
+ * @param pRLEBytes CEL pixel stream (run-length encoded)
+ * @param nDataSize Size of CEL in bytes
+ * @param nWidth Width of sprite
+ */
 void CelBlitLightTrans(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth)
 {
 	int w;
@@ -596,6 +655,14 @@ void CelBlitLightTrans(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWid
 #endif
 }
 
+/**
+ * @brief Blit CEL sprite, and apply lighting, to the back buffer at the given coordinates
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
+ * @param pCelBuff Cel data
+ * @param nCel CEL frame number
+ * @param nWidth Width of sprite
+ */
 void CelDrawLight(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth)
 {
 	int nDataSize;
@@ -618,6 +685,12 @@ void CelDrawLight(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth)
 }
 
 /**
+ * @brief Same as CelDrawLight but with the option to skip parts of the top and bottom of the sprite
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
+ * @param pCelBuff Cel data
+ * @param nCel CEL frame number
+ * @param nWidth Width of sprite
  * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8
  * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8
  */
@@ -661,6 +734,11 @@ void CelClippedDrawLight(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, i
 }
 
 /**
+ * @brief Same as CelBlitLightTrans but with the option to skip parts of the top and bottom of the sprite
+ * @param pBuff Target buffer
+ * @param pCelBuff Cel data
+ * @param nCel CEL frame number
+ * @param nWidth Width of sprite
  * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8
  * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8
  */
@@ -705,8 +783,15 @@ void CelClippedBlitLightTrans(BYTE *pBuff, BYTE *pCelBuff, int nCel, int nWidth,
 }
 
 /**
+ * @brief Blit CEL sprite, and apply lighting, to the back buffer at the given coordinates, translated to a red hue
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
+ * @param pCelBuff Cel data
+ * @param nCel CEL frame number
+ * @param nWidth Width of sprite
  * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8
  * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8
+ * @param light Light shade to use
  */
 void CelDrawLightRed(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, int CelSkip, int CelCap, char light)
 {
@@ -823,6 +908,10 @@ void CelDrawLightRed(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, int C
 
 /**
  * @brief Same as CelBlit but checks for drawing outside the buffer
+ * @param pDecodeTo The output buffer
+ * @param pRLEBytes CEL pixel stream (run-length encoded)
+ * @param nDataSize Size of CEL in bytes
+ * @param nWidth Width of sprite
  */
 void CelBlitSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth)
 {
@@ -938,6 +1027,12 @@ void CelBlitSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth)
 }
 
 /**
+ * @brief Same as CelClippedDraw but checks for drawing outside the buffer
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
+ * @param pCelBuff Cel data
+ * @param nCel CEL frame number
+ * @param nWidth Width of sprite
  * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8
  * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8
  */
@@ -979,6 +1074,11 @@ void CelClippedDrawSafe(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, in
 }
 
 /**
+ * @brief Same as CelClippedBlit but checks for drawing outside the buffer
+ * @param pBuff Target buffer
+ * @param pCelBuff Cel data
+ * @param nCel CEL frame number
+ * @param nWidth Width of sprite
  * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8
  * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8
  */
@@ -1017,6 +1117,10 @@ void CelClippedBlitSafe(BYTE *pBuff, BYTE *pCelBuff, int nCel, int nWidth, int C
 
 /**
  * @brief Same as CelBlitLight but checks for drawing outside the buffer
+ * @param pDecodeTo The output buffer
+ * @param pRLEBytes CEL pixel stream (run-length encoded)
+ * @param nDataSize Size of CEL in bytes
+ * @param nWidth Width of sprite
  */
 void CelBlitLightSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth)
 {
@@ -1188,6 +1292,10 @@ void CelBlitLightSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidt
 
 /**
  * @brief Same as CelBlitLightTrans but checks for drawing outside the buffer
+ * @param pDecodeTo The output buffer
+ * @param pRLEBytes CEL pixel stream (run-length encoded)
+ * @param nDataSize Size of CEL in bytes
+ * @param nWidth Width of sprite
  */
 void CelBlitLightTransSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth)
 {
@@ -1391,6 +1499,12 @@ void CelBlitLightTransSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int
 }
 
 /**
+ * @brief Same as CelDrawLight but checks for drawing outside the buffer
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
+ * @param pCelBuff Cel data
+ * @param nCel CEL frame number
+ * @param nWidth Width of cel
  * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8
  * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8
  */
@@ -1434,6 +1548,11 @@ void CelDrawLightSafe(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, int
 }
 
 /**
+ * @brief Same as CelClippedBlitLightTrans but checks for drawing outside the buffer
+ * @param pBuff Target buffer
+ * @param pCelBuff Cel data
+ * @param nCel CEL frame number
+ * @param nWidth Width of cel
  * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8
  * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8
  */
@@ -1476,8 +1595,14 @@ void CelClippedBlitLightTransSafe(BYTE *pBuff, BYTE *pCelBuff, int nCel, int nWi
 
 /**
  * @brief Same as CelDrawLightRed but checks for drawing outside the buffer
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
+ * @param pCelBuff Cel data
+ * @param nCel CEL frame number
+ * @param nWidth Width of cel
  * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8
  * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8
+ * @param light Light shade to use
  */
 void CelDrawLightRedSafe(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, int CelSkip, int CelCap, char light)
 {
@@ -1607,7 +1732,7 @@ void CelDrawLightRedSafe(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, i
  * @param y Cordinate in pBuff buffer
  * @param wdt Width of pBuff
  * @param pCelBuff Cel data
- * @param nCel Frame of cel
+ * @param nCel CEL frame number
  * @param nWidth Width of cel
  */
 void CelBlitWidth(BYTE *pBuff, int x, int y, int wdt, BYTE *pCelBuff, int nCel, int nWidth)
@@ -1725,6 +1850,13 @@ void CelBlitWidth(BYTE *pBuff, int x, int y, int wdt, BYTE *pCelBuff, int nCel,
 }
 
 /**
+ * @brief Blit a solid colder shape one pixel larger then the given sprite shape, to the back buffer at the given coordianates
+ * @param col Color index from current palette
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
+ * @param pCelBuff CEL buffer
+ * @param nCel CEL frame number
+ * @param nWidth Width of sprite
  * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8
  * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8
  */
@@ -1867,6 +1999,12 @@ void CelBlitOutline(char col, int sx, int sy, BYTE *pCelBuff, int nCel, int nWid
 
 /**
  * @brief Same as CelBlitOutline but checks for drawing outside the buffer
+ * @param col Color index from current palette
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
+ * @param pCelBuff CEL buffer
+ * @param nCel CEL frame number
+ * @param nWidth Width of sprite
  * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8
  * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8
  */
@@ -2049,6 +2187,12 @@ void CelBlitOutlineSafe(char col, int sx, int sy, BYTE *pCelBuff, int nCel, int
 #endif
 }
 
+/**
+ * @brief Set the value of a single pixel in the back buffer, checks bounds
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
+ * @param col Color index from current palette
+ */
 void ENG_set_pixel(int sx, int sy, BYTE col)
 {
 	BYTE *dst;
@@ -2075,6 +2219,11 @@ void ENG_set_pixel(int sx, int sy, BYTE col)
 #endif
 }
 
+/**
+ * @brief Set the value of a single pixel in the back buffer to that of gbPixelCol, checks bounds
+ * @param sx Back buffer coordinate
+ * @param sy Back buffer coordinate
+ */
 void engine_draw_pixel(int sx, int sy)
 {
 	BYTE *dst;
@@ -2106,18 +2255,6 @@ void engine_draw_pixel(int sx, int sy)
 #endif
 }
 
-// Exact copy from https://github.com/erich666/GraphicsGems/blob/dad26f941e12c8bf1f96ea21c1c04cd2206ae7c9/gems/DoubleLine.c
-// Except:
-// * not in view checks
-// * global variable instead of reverse flag
-// * condition for pixels_left < 0 removed
-
-/*
-Symmetric Double Step Line Algorithm
-by Brian Wyvill
-from "Graphics Gems", Academic Press, 1990
-*/
-
 #define GG_SWAP(A, B) \
 	{                 \
 		(A) ^= (B);   \
@@ -2126,6 +2263,24 @@ from "Graphics Gems", Academic Press, 1990
 	}
 #define GG_ABSOLUTE(I, J, K) (((I) - (J)) * ((K) = (((I) - (J)) < 0 ? -1 : 1)))
 
+/**
+ * Symmetric Double Step Line Algorithm
+ * by Brian Wyvill
+ * from "Graphics Gems", Academic Press, 1990
+ *
+ * Exact copy from https://github.com/erich666/GraphicsGems/blob/dad26f941e12c8bf1f96ea21c1c04cd2206ae7c9/gems/DoubleLine.c
+ * Except:
+ * - not in view checks
+ * - global variable instead of reverse flag
+ * - condition for pixels_left < 0 removed
+ *
+ * @brief Draw a line on the back buffer
+ * @param x0 Back buffer coordinate
+ * @param y0 Back buffer coordinate
+ * @param x1 Back buffer coordinate
+ * @param y1 Back buffer coordinate
+ * @param col Color index from current palette
+ */
 void DrawLine(int x0, int y0, int x1, int y1, BYTE col)
 {
 	int dx, dy, incr1, incr2, D, x, y, xend, c, pixels_left;
@@ -2315,6 +2470,14 @@ void DrawLine(int x0, int y0, int x1, int y1, BYTE col)
 	}
 }
 
+/**
+ * @brief Calculate the best fit direction between two points
+ * @param x1 Tile coordinate
+ * @param y1 Tile coordinate
+ * @param x2 Tile coordinate
+ * @param y2 Tile coordinate
+ * @return A value from the direction enum
+ */
 int GetDirection(int x1, int y1, int x2, int y2)
 {
 	int mx, my;
@@ -2356,6 +2519,10 @@ int GetDirection(int x1, int y1, int x2, int y2)
 	return md;
 }
 
+/**
+ * @brief Set the RNG seed
+ * @param s RNG seed
+ */
 void SetRndSeed(int s)
 {
 	SeedCount = 0;
@@ -2363,6 +2530,10 @@ void SetRndSeed(int s)
 	orgseed = s;
 }
 
+/**
+ * @brief Get the current RNG seed
+ * @return RNG seed
+ */
 int GetRndSeed()
 {
 	SeedCount++;
@@ -2370,6 +2541,12 @@ int GetRndSeed()
 	return abs(sglGameSeed);
 }
 
+/**
+ * @brief Main RNG function
+ * @param idx Unused
+ * @param v The upper limit for the return value
+ * @return A random number from 0 to (v-1)
+ */
 int random_(BYTE idx, int v)
 {
 	if (v <= 0)
@@ -2394,6 +2571,10 @@ void engine_debug_trap(BOOL show_cursor)
 */
 }
 
+/**
+ * @brief Multithreaded safe malloc
+ * @param dwBytes Byte size to allocate
+ */
 BYTE *DiabloAllocPtr(DWORD dwBytes)
 {
 	BYTE *buf;
@@ -2413,6 +2594,10 @@ BYTE *DiabloAllocPtr(DWORD dwBytes)
 	return buf;
 }
 
+/**
+ * @brief Multithreaded safe memfree
+ * @param p Memory pointer to free
+ */
 void mem_free_dbg(void *p)
 {
 	if (p) {
@@ -2426,6 +2611,12 @@ void mem_free_dbg(void *p)
 	}
 }
 
+/**
+ * @brief Load a file in to a buffer
+ * @param pszName Path of file
+ * @param pdwFileLen Will be set to file size if non-NULL
+ * @return Buffer with content of file
+ */
 BYTE *LoadFileInMem(char *pszName, DWORD *pdwFileLen)
 {
 	HANDLE file;
@@ -2449,6 +2640,12 @@ BYTE *LoadFileInMem(char *pszName, DWORD *pdwFileLen)
 	return buf;
 }
 
+/**
+ * @brief Load a file in to the given buffer
+ * @param pszName Path of file
+ * @param p Target buffer
+ * @return Size of file
+ */
 DWORD LoadFileWithMem(const char *pszName, void *p)
 {
 	DWORD dwFileLen;
@@ -2713,7 +2910,7 @@ void Cl2Blit(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth)
 }
 
 /**
- * @brief Blit a solid colder shape one pix larger then the given sprite shape, to the back buffer at the given coordianates
+ * @brief Blit a solid colder shape one pixel larger then the given sprite shape, to the back buffer at the given coordianates
  * @param col Color index from current palette
  * @param sx Back buffer coordinate
  * @param sy Back buffer coordinate
@@ -2762,7 +2959,7 @@ void Cl2DrawOutline(char col, int sx, int sy, BYTE *pCelBuff, int nCel, int nWid
 }
 
 /**
- * @brief Blit a solid colder shape one pix larger then the given sprite shape, to the given buffer
+ * @brief Blit a solid colder shape one pixel larger then the given sprite shape, to the given buffer
  * @param pDecodeTo The output buffer
  * @param pRLEBytes CL2 pixel stream (run-length encoded)
  * @param nDataSize Size of CL2 in bytes
@@ -3199,7 +3396,7 @@ void Cl2DrawLight(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, int CelS
 }
 
 /**
- * @brief Blit CL2 sprite to the back buffer, while checking bounds, at the given coordianates
+ * @brief Same as Cl2Draw but checks for drawing outside the buffer
  * @param sx Back buffer coordinate
  * @param sy Back buffer coordinate
  * @param pCelBuff CL2 buffer
@@ -3246,7 +3443,7 @@ void Cl2DrawSafe(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, int CelSk
 }
 
 /**
- * @brief Blit CL2 sprite to pDecodeTo while checking bounds
+ * @brief Same as Cl2Blit but checks for drawing outside the buffer
  * @param pDecodeTo The output buffer
  * @param pRLEBytes CL2 pixel stream (run-length encoded)
  * @param nDataSize Size of CL2 in bytes
@@ -3407,7 +3604,7 @@ void Cl2BlitSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth)
 }
 
 /**
- * @brief Blit a solid colder shape one pix larger then the given sprite shape, to the back buffer at the given coordianates, while checking bounds
+ * @brief Same as Cl2DrawOutline but checks for drawing outside the buffer
  * @param col Color index from current palette
  * @param sx Back buffer coordinate
  * @param sy Back buffer coordinate
@@ -3458,7 +3655,7 @@ void Cl2DrawOutlineSafe(char col, int sx, int sy, BYTE *pCelBuff, int nCel, int
 }
 
 /**
- * @brief Blit a solid colder shape one pix larger then the given sprite shape, to the given buffer, while checking bounds
+ * @brief Same as Cl2BlitOutline but checks for drawing outside the buffer
  * @param pDecodeTo The output buffer
  * @param pRLEBytes CL2 pixel stream (run-length encoded)
  * @param nDataSize Size of CL2 in bytes
@@ -3639,7 +3836,7 @@ void Cl2BlitOutlineSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWi
 }
 
 /**
- * @brief Blit CL2 sprite, and apply a given lighting, to the back buffer at the given coordianates, while checking bounds
+ * @brief Same as Cl2DrawLightTbl but checks for drawing outside the buffer
  * @param sx Back buffer coordinate
  * @param sy Back buffer coordinate
  * @param pCelBuff CL2 buffer
@@ -3698,7 +3895,7 @@ void Cl2DrawLightTblSafe(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, i
 }
 
 /**
- * @brief Blit CL2 sprite, and apply light, to pDecodeTo while checking bounds
+ * @brief Same as Cl2BlitLight but checks for drawing outside the buffer
  * @param pDecodeTo The output buffer
  * @param pRLEBytes CL2 pixel stream (run-length encoded)
  * @param nDataSize Size of CL2 in bytes
@@ -3869,7 +4066,7 @@ void Cl2BlitLightSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidt
 }
 
 /**
- * @brief Blit CL2 sprite, and apply lighting, to the back buffer at the given coordinates, while checking bounds
+ * @brief Same as Cl2DrawLight but checks for drawing outside the buffer
  * @param sx Back buffer coordinate
  * @param sy Back buffer coordinate
  * @param pCelBuff CL2 buffer

From e7e51abd135e64f639e774999b1851ee176d3970 Mon Sep 17 00:00:00 2001
From: Anders Jenbo <anders@jenbo.dk>
Date: Sun, 16 Feb 2020 03:39:04 +0100
Subject: [PATCH 3/4] Document remaning functions in render related files

---
 Source/engine.cpp   |  4 ++++
 Source/render.cpp   | 32 ++++++++++++++++++++++++++++++++
 Source/scrollrt.cpp | 32 ++++++++++++++++++++++++++++++++
 Source/town.cpp     |  3 +++
 4 files changed, 71 insertions(+)

diff --git a/Source/engine.cpp b/Source/engine.cpp
index 5836aafa6..13a86bfc7 100644
--- a/Source/engine.cpp
+++ b/Source/engine.cpp
@@ -2556,6 +2556,10 @@ int random_(BYTE idx, int v)
 	return GetRndSeed() % v;
 }
 
+/**
+ * @brief Unallocate all remaining pointers
+ * @param show_cursor unused
+ */
 void engine_debug_trap(BOOL show_cursor)
 {
 	/*
diff --git a/Source/render.cpp b/Source/render.cpp
index c4ff1e4d9..39a22cb31 100644
--- a/Source/render.cpp
+++ b/Source/render.cpp
@@ -114,6 +114,11 @@ int WorldTbl17_2[17] = { 0, 32, 60, 88, 112, 136, 156, 176, 192, 208, 220, 232,
 #ifdef USE_ASM
 #include "_render.cpp"
 #else
+/**
+ * While blitting this function will check for the upper bound of the buffer
+ * @brief Blit upper part of transparent world CELs
+ * @param pBuff Output buffer
+ */
 void drawTopArchesUpperScreen(BYTE *pBuff)
 {
 	BYTE *dst, *src;
@@ -1137,6 +1142,12 @@ void drawTopArchesUpperScreen(BYTE *pBuff)
 	}
 }
 
+/**
+ * While blitting this function will check for the upper bound of the buffer
+ * @brief Blit lower part of transparent world CELs
+ * @param pBuff Output buffer
+ * @param pMask Transparancy pattern
+ */
 void drawBottomArchesUpperScreen(BYTE *pBuff, DWORD *pMask)
 {
 	BYTE *dst, *src;
@@ -1769,6 +1780,11 @@ void drawBottomArchesUpperScreen(BYTE *pBuff, DWORD *pMask)
 	}
 }
 
+/**
+ * While blitting this function will check for the upper bound of the buffer
+ * @brief Blit current world CEL to the given buffer
+ * @param pBuff Output buffer
+ */
 void drawUpperScreen(BYTE *pBuff)
 {
 	BYTE *dst, *src;
@@ -2386,6 +2402,11 @@ void drawUpperScreen(BYTE *pBuff)
 	}
 }
 
+/**
+ * While blitting this function will check for the lower bound of the buffer
+ * @brief Blit upper part of transparent world CELs
+ * @param pBuff Output buffer
+ */
 void drawTopArchesLowerScreen(BYTE *pBuff)
 {
 	BYTE *dst, *src;
@@ -3622,6 +3643,12 @@ LABEL_11:
 	}
 }
 
+/**
+ * While blitting this function will check for the lower bound of the buffer
+ * @brief Blit lower part of transparent world CELs
+ * @param pBuff Output buffer
+ * @param pMask Transparancy pattern
+ */
 void drawBottomArchesLowerScreen(BYTE *pBuff, DWORD *pMask)
 {
 	BYTE *dst, *src;
@@ -4414,6 +4441,11 @@ void drawBottomArchesLowerScreen(BYTE *pBuff, DWORD *pMask)
 	}
 }
 
+/**
+ * While blitting this function will check for the lower bound of the buffer
+ * @brief Blit current world CEL to the given buffer
+ * @param pBuff Output buffer
+ */
 void drawLowerScreen(BYTE *pBuff)
 {
 	BYTE *dst, *src;
diff --git a/Source/scrollrt.cpp b/Source/scrollrt.cpp
index 92c5d8e4e..b2508db1c 100644
--- a/Source/scrollrt.cpp
+++ b/Source/scrollrt.cpp
@@ -1,23 +1,51 @@
 #include "all.h"
 #include "../3rdParty/Storm/Source/storm.h"
 
+/**
+ * Specifies the current light entry.
+ */
 int light_table_index;
 int PitchTbl[1024];
 DWORD sgdwCursWdtOld;
 DWORD sgdwCursX;
 DWORD sgdwCursY;
+/**
+ * Lower bound of back buffer.
+ */
 BYTE *gpBufEnd;
 DWORD sgdwCursHgt;
+
+/**
+ * Specifies the current MIN block of the level CEL file, as used during rendering of the level tiles.
+ *
+ * frameNum  := block & 0x0FFF
+ * frameType := block & 0x7000 >> 12
+ */
 DWORD level_cel_block;
 DWORD sgdwCursXOld;
 DWORD sgdwCursYOld;
+/**
+ * Specifies the type of arches to render.
+ */
 char arch_draw_type;
+/**
+ * Describes the surface being rendered.
+ */
 DDSURFACEDESC DDS_desc;
+/**
+ * Specifies whether transparency is active for the current CEL file being decoded.
+ */
 int cel_transparency_active;
+/**
+ * Specifies the current dungeon piece ID of the level, as used during rendering of the level tiles.
+ */
 int level_piece_id;
 DWORD sgdwCursWdt;
 void (*DrawPlrProc)(int, int, int, int, int, BYTE *, int, int, int, int);
 BYTE sgSaveBack[8192];
+/**
+ * Specifies the monster_num to render.
+ */
 int draw_monster_num;
 DWORD sgdwCursHgtOld;
 
@@ -2800,6 +2828,10 @@ static void DrawMain(int dwHgt, BOOL draw_desc, BOOL draw_hp, BOOL draw_mana, BO
 #endif
 }
 
+/**
+ * @brief Redraw screen
+ * @param draw_cursor
+ */
 void scrollrt_draw_game_screen(BOOL draw_cursor)
 {
 	int hgt;
diff --git a/Source/town.cpp b/Source/town.cpp
index 3289caaf8..dc7904d5b 100644
--- a/Source/town.cpp
+++ b/Source/town.cpp
@@ -1396,6 +1396,9 @@ void T_DrawView(int StartX, int StartY)
 	DrawManaFlask();
 }
 
+/**
+ * @brief Build tile columns
+ */
 void SetTownMicros()
 {
 	int i, x, y, lv;

From ab453a5bb03f8eb6e14fbcafaea7b02d6c0ec594 Mon Sep 17 00:00:00 2001
From: Anders Jenbo <anders@jenbo.dk>
Date: Sun, 16 Feb 2020 04:59:51 +0100
Subject: [PATCH 4/4] Correct some documentation

---
 Source/scrollrt.cpp | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/Source/scrollrt.cpp b/Source/scrollrt.cpp
index b2508db1c..1fcd527a0 100644
--- a/Source/scrollrt.cpp
+++ b/Source/scrollrt.cpp
@@ -88,6 +88,9 @@ char *szPlrModeAssert[12] = {
 	"quitting"
 };
 
+/**
+ * @brief Clear cursor state
+ */
 void ClearCursor() // CODE_FIX: this was supposed to be in cursor.cpp
 {
 	sgdwCursWdt = 0;
@@ -204,7 +207,7 @@ static void scrollrt_draw_cursor_item()
 }
 
 /**
- * @brief Render a missile sprite
+ * @brief Render a missile sprites for a given tile
  * @param x dPiece coordinate
  * @param y dPiece coordinate
  * @param sx Back buffer coordinate
@@ -470,7 +473,7 @@ static void DrawClippedMonster(int x, int y, int mx, int my, int m, int CelSkip,
 }
 
 /**
- * @brief Render a monster sprite
+ * @brief Render a player sprite
  * @param pnum Player id
  * @param x dPiece coordinate
  * @param y dPiece coordinate
@@ -642,7 +645,7 @@ static void DrawClippedPlayer(int pnum, int x, int y, int px, int py, BYTE *pCel
 }
 
 /**
- * @brief Render a monster sprite
+ * @brief Render a player sprite
  * @param x dPiece coordinate
  * @param y dPiece coordinate
  * @param sx Back buffer coordinate