From 31ac716c3d11c7db66e599ba01ef0d571c6cbe61 Mon Sep 17 00:00:00 2001
From: Anders Jenbo <anders@jenbo.dk>
Date: Tue, 7 Jul 2020 19:36:18 +0200
Subject: [PATCH] 99 lines of documentation (#2058)

---
 Source/appfat.cpp   | 15 +++++++++++++++
 Source/capture.cpp  | 31 +++++++++++++++++++++++++++++++
 Source/cursor.cpp   | 15 +++++++++++++++
 Source/drlg_l3.cpp  |  3 +++
 Source/engine.cpp   |  4 +++-
 Source/init.cpp     |  2 ++
 Source/inv.cpp      |  3 +++
 Source/loadsave.cpp |  4 ++++
 Source/movie.cpp    |  9 +++++++++
 Source/restrict.cpp | 14 ++++++++++++++
 Source/setmaps.cpp  |  3 +++
 Source/towners.cpp  |  4 ++++
 12 files changed, 106 insertions(+), 1 deletion(-)

diff --git a/Source/appfat.cpp b/Source/appfat.cpp
index b6d38c35a..e7a4cfb02 100644
--- a/Source/appfat.cpp
+++ b/Source/appfat.cpp
@@ -6,6 +6,7 @@
 #include "all.h"
 #include "../3rdParty/Storm/Source/storm.h"
 
+/** Buffer used by GetErrorStr for it's return value */
 char sz_error_buf[256];
 /** Set to true when a fatal error is encountered and the application should shut down. */
 BOOL terminating;
@@ -57,6 +58,8 @@ LONG __stdcall BreakFilter(PEXCEPTION_POINTERS pExc)
 
 /**
  * @brief Returns a formatted error message based on the given error code.
+ * @param error_code DirectX error code
+
  */
 char *GetErrorStr(DWORD error_code)
 {
@@ -475,6 +478,8 @@ char *TraceLastError()
 
 /**
  * @brief Terminates the game and displays an error message box.
+ * @param pszFmt Optional error message.
+ * @param ... (see printf)
  */
 void __cdecl app_fatal(const char *pszFmt, ...)
 {
@@ -498,6 +503,8 @@ void __cdecl app_fatal(const char *pszFmt, ...)
 
 /**
  * @brief Displays an error message box based on the given format string and variable argument list.
+ * @param pszFmt Error message format
+ * @param va Additional parameters for message format
  */
 void MsgBox(const char *pszFmt, va_list va)
 {
@@ -533,6 +540,8 @@ void FreeDlg()
 
 /**
  * @brief Displays a warning message box based on the given formatted error message.
+ * @param pszFmt Error message format
+ * @param ... Additional parameters for message format
  */
 void __cdecl DrawDlg(char *pszFmt, ...)
 {
@@ -546,6 +555,12 @@ void __cdecl DrawDlg(char *pszFmt, ...)
 }
 
 #ifdef _DEBUG
+/**
+ * @brief Show an error and exit the application.
+ * @param nLineNo The line number of the assertion
+ * @param pszFile File name where the assertion is located
+ * @param pszFail Fail message
+ */
 void assert_fail(int nLineNo, const char *pszFile, const char *pszFail)
 {
 	app_fatal("assertion failed (%d:%s)\n%s", nLineNo, pszFile, pszFail);
diff --git a/Source/capture.cpp b/Source/capture.cpp
index 44c4f4b00..aec553bb4 100644
--- a/Source/capture.cpp
+++ b/Source/capture.cpp
@@ -32,6 +32,12 @@ static BOOL CaptureHdr(HANDLE hFile, short width, short height)
 	return WriteFile(hFile, &Buffer, sizeof(Buffer), &lpNumBytes, NULL) && lpNumBytes == sizeof(Buffer);
 }
 
+/**
+ * @brief Write the current ingame palette to the PCX file
+ * @param hFile File handler for the PCX file.
+ * @param palette Current palette
+ * @return True if successful, else false
+ */
 static BOOL CapturePal(HANDLE hFile, PALETTEENTRY *palette)
 {
 	DWORD NumberOfBytesWritten;
@@ -48,6 +54,14 @@ static BOOL CapturePal(HANDLE hFile, PALETTEENTRY *palette)
 	return WriteFile(hFile, pcx_palette, sizeof(pcx_palette), &NumberOfBytesWritten, NULL) && NumberOfBytesWritten == sizeof(pcx_palette);
 }
 
+/**
+ * @brief RLE compress the pixel data
+ * @param src Raw pixel buffer
+ * @param dst Output buffer
+ * @param width Width of pixel buffer
+
+ * @return Output buffer
+ */
 static BYTE *CaptureEnc(BYTE *src, BYTE *dst, int width)
 {
 	int rleLength;
@@ -82,6 +96,15 @@ static BYTE *CaptureEnc(BYTE *src, BYTE *dst, int width)
 	return dst;
 }
 
+/**
+ * @brief Write the pixel data to the PCX file
+ * @param hFile File handler for the PCX file.
+ * @param width Image width
+ * @param height Image height
+ * @param stride Buffer width
+ * @param pixels Raw pixel buffer
+ * @return True if successful, else false
+ */
 static BOOL CapturePix(HANDLE hFile, WORD width, WORD height, WORD stride, BYTE *pixels)
 {
 	int writeSize;
@@ -129,6 +152,10 @@ static HANDLE CaptureFile(char *dst_path)
 	return INVALID_HANDLE_VALUE;
 }
 
+/**
+ * @brief Make a red version of the given palette and apply it to the screen.
+ * @param pal The original palette
+ */
 static void RedPalette(PALETTEENTRY *pal)
 {
 	PALETTEENTRY red[256];
@@ -144,6 +171,10 @@ static void RedPalette(PALETTEENTRY *pal)
 	lpDDPalette->SetEntries(0, 0, 256, red);
 }
 
+/**
+ * @brief Save the current screen to a screen??.PCX (00-99) in file if available, then make the screen red for 200ms.
+
+ */
 void CaptureScreen()
 {
 	HANDLE hObject;
diff --git a/Source/cursor.cpp b/Source/cursor.cpp
index 9a2675a61..65f9b3586 100644
--- a/Source/cursor.cpp
+++ b/Source/cursor.cpp
@@ -5,23 +5,38 @@
  */
 #include "all.h"
 
+/** Pixel width of the current cursor image */
 int cursW;
+/** Pixel height of the current cursor image */
 int cursH;
+/** Current highlighted monster */
 int pcursmonst;
+/** Width of current cursor in inventory cells */
 int icursW28;
+/** Height of current cursor in inventory cells */
 int icursH28;
+/** Cursor images CEL */
 BYTE *pCursCels;
 
 /** inv_item value */
 char pcursinvitem;
+/** Pixel width of the current cursor image */
 int icursW;
+/** Pixel height of the current cursor image */
 int icursH;
+/** Current highlighted item */
 char pcursitem;
+/** Current highlighted object */
 char pcursobj;
+/** Current highlighted player */
 char pcursplr;
+/** Current highlighted tile row */
 int cursmx;
+/** Current highlighted tile column */
 int cursmy;
+/** Previously highlighted monster */
 int pcurstemp;
+/** Index of current cursor image */
 int pcurs;
 
 /* rdata */
diff --git a/Source/drlg_l3.cpp b/Source/drlg_l3.cpp
index ecb085d08..4cc0844f4 100644
--- a/Source/drlg_l3.cpp
+++ b/Source/drlg_l3.cpp
@@ -6,7 +6,10 @@
 #ifndef SPAWN
 #include "all.h"
 
+/** This will be true if a lava pool has been generated for the level */
+
 BOOLEAN lavapool;
+/** unused */
 int abyssx;
 int lockoutcnt;
 BOOLEAN lockout[DMAXX][DMAXY];
diff --git a/Source/engine.cpp b/Source/engine.cpp
index 267f4e02a..de2f34ae3 100644
--- a/Source/engine.cpp
+++ b/Source/engine.cpp
@@ -17,7 +17,8 @@
 #pragma warning(disable : 4731) // frame pointer register 'ebp' modified by inline assembly code
 #endif
 
-char gbPixelCol;  // automap pixel color 8-bit (palette entry)
+/** automap pixel color 8-bit (palette entry) */
+char gbPixelCol;
 BOOL gbRotateMap; // flip - if y < x
 int orgseed;
 /** Width of sprite being blitted */
@@ -25,6 +26,7 @@ int sgnWidth;
 /** Current game seed */
 int sglGameSeed;
 static CCritSect sgMemCrit;
+/** Number of times the current seed has been fetched */
 int SeedCount;
 BOOL gbNotInView; // valid - if x/y are in bounds
 
diff --git a/Source/init.cpp b/Source/init.cpp
index 61213e60c..d72620827 100644
--- a/Source/init.cpp
+++ b/Source/init.cpp
@@ -8,6 +8,7 @@
 #include "../DiabloUI/diabloui.h"
 
 _SNETVERSIONDATA fileinfo;
+/** True if the game is the current active window */
 int gbActive;
 /** Specifies the path to diablo.exe. */
 char diablo_exe_path[MAX_PATH];
@@ -15,6 +16,7 @@ char diablo_exe_path[MAX_PATH];
 HANDLE hellfire_mpq;
 /** Specifies the path to patch_rt.mpq. */
 char patch_rt_mpq_path[MAX_PATH];
+/** The current input handler function */
 WNDPROC CurrentProc;
 /** A handle to the diabdat.mpq archive. */
 HANDLE diabdat_mpq;
diff --git a/Source/inv.cpp b/Source/inv.cpp
index 618fc8289..23415eba6 100644
--- a/Source/inv.cpp
+++ b/Source/inv.cpp
@@ -188,6 +188,9 @@ void InvDrawSlotBack(int X, int Y, int W, int H)
 #endif
 }
 
+/**
+ * @brief Render the inventory panel to the back buffer
+ */
 void DrawInv()
 {
 	BOOL invtest[NUM_INV_GRID_ELEM];
diff --git a/Source/loadsave.cpp b/Source/loadsave.cpp
index 352a6dc38..8839b7ca7 100644
--- a/Source/loadsave.cpp
+++ b/Source/loadsave.cpp
@@ -7,6 +7,10 @@
 
 BYTE *tbuff;
 
+/**
+ * @brief Load game state
+ * @param firstflag Can be set to false if we are simply reloading the current game
+ */
 void LoadGame(BOOL firstflag)
 {
 	int i, j;
diff --git a/Source/movie.cpp b/Source/movie.cpp
index 4b1ec3484..2fb9d7d1c 100644
--- a/Source/movie.cpp
+++ b/Source/movie.cpp
@@ -11,6 +11,11 @@ BYTE movie_playing;
 /** Should the movie play in a loop. */
 BOOL loop_movie;
 
+/**
+ * @brief Start playback of a given video.
+ * @param pszMovie The file name of the video
+ * @param user_can_close Set to false to make the video unskippable.
+ */
 void play_movie(char *pszMovie, BOOL user_can_close)
 {
 	WNDPROC saveProc;
@@ -50,6 +55,10 @@ void play_movie(char *pszMovie, BOOL user_can_close)
 	sound_disable_music(FALSE);
 }
 
+/**
+ * @brief Input handeler for use during vidoe playback.
+ * @see WNDPROC
+ */
 LRESULT __stdcall MovieWndProc(HWND hWnd, UINT Msg, WPARAM wParam, LPARAM lParam)
 {
 	switch (Msg) {
diff --git a/Source/restrict.cpp b/Source/restrict.cpp
index 4f4fed25f..5774888f2 100644
--- a/Source/restrict.cpp
+++ b/Source/restrict.cpp
@@ -5,6 +5,10 @@
  */
 #include "all.h"
 
+/**
+ * @brief Check that the OS version is the minimum required by the game
+ * @return True if suported
+ */
 BOOL SystemSupported()
 {
 	OSVERSIONINFO VersionInformation;
@@ -20,6 +24,11 @@ BOOL SystemSupported()
 	return ret;
 }
 
+/**
+ * @brief Check that we have write access to the Windows install folder
+ * @return False if we have write access
+
+ */
 BOOL RestrictedTest()
 {
 	FILE *f;
@@ -39,6 +48,11 @@ BOOL RestrictedTest()
 	return ret;
 }
 
+/**
+ * @brief Check that we have write access to the game install folder
+ * @return False if we have write access
+
+ */
 BOOL ReadOnlyTest()
 {
 	char *c;
diff --git a/Source/setmaps.cpp b/Source/setmaps.cpp
index 86645de2e..5c3035796 100644
--- a/Source/setmaps.cpp
+++ b/Source/setmaps.cpp
@@ -134,6 +134,9 @@ void DRLG_SetMapTrans(char *sFileName)
 	mem_free_dbg(pLevelMap);
 }
 
+/**
+ * @brief Load a quest map, the given map is specified via the global setlvlnum
+ */
 void LoadSetMap()
 {
 	switch (setlvlnum) {
diff --git a/Source/towners.cpp b/Source/towners.cpp
index cdca244cd..8e0b84f8c 100644
--- a/Source/towners.cpp
+++ b/Source/towners.cpp
@@ -218,6 +218,10 @@ void InitQstSnds(int i)
 	}
 }
 
+/**
+ * @brief Load Griswold into the game
+
+ */
 void InitSmith()
 {
 	int i;