Add documentation

- Add file documentation to about 1/4 of the files in Source
- Copy over a lot of the documentation from the sanctuary/notes repo
- Standardise all the existing documentation
- Create a configuration for Doxygen
- Add more documentation (engine.cpp is now fully documented)

.gitignore

@@ -373,3 +373,4 @@ ASALocalRun/
 *.pubxml.user
 
 # End of https://www.gitignore.io/api/visualstudio
+/docs/html/

Source/all.h

@@ -1,3 +1,8 @@
+/**
+ * @file all.h
+ *
+ * Include all aplication headers.
+ */
 #ifndef __ALL_H__
 #define __ALL_H__
 

Source/appfat.cpp

@@ -1,8 +1,15 @@
+/**
+ * @file appfat.cpp
+ *
+ * Implementation of error dialogs.
+ */
 #include "all.h"
 #include "../3rdParty/Storm/Source/storm.h"
 
 char sz_error_buf[256];
+/** Set to true when a fatal error is encountered and the application should shut down. */
 BOOL terminating;
+/** Thread id of the last callee to FreeDlg(). */
 int cleanup_thread_id;
 
 // delete overloads the delete operator.
@@ -80,6 +87,12 @@ char *GetErrorStr(DWORD error_code)
 	return sz_error_buf;
 }
 
+/**
+ * @brief Generate a textual message for DirectDraw error codes
+ * @param hError DirectDraw error code
+ * @param pszBuffer Buffer for the error message
+ * @param dwMaxChars Length of pszBuffer
+ */
 void TraceErrorDD(HRESULT hError, char *pszBuffer, DWORD dwMaxChars)
 {
 	const char *szError;
@@ -390,6 +403,12 @@ void TraceErrorDD(HRESULT hError, char *pszBuffer, DWORD dwMaxChars)
 	strncpy(pszBuffer, szError, dwMaxChars);
 }
 
+/**
+ * @brief Generate a textual message for DirectSound error codes
+ * @param hError DirectSound error code
+ * @param pszBuffer Buffer for the error message
+ * @param dwMaxChars Length of pszBuffer
+ */
 void TraceErrorDS(HRESULT hError, char *pszBuffer, DWORD dwMaxChars)
 {
 	const char *szError;

Source/appfat.h

@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file appfat.h
+ *
+ * Interface of error dialogs.
+ */
 #ifndef __APPFAT_H__
 #define __APPFAT_H__
 

Source/automap.cpp

@@ -1,3 +1,8 @@
+/**
+ * @file automap.cpp
+ *
+ * Implementation of the ingame map overlay.
+ */
 #include "all.h"
 
 // BUGFIX: only the first 256 elements are ever read
@@ -16,15 +21,15 @@ int AmLine16;
 int AmLine8;
 int AmLine4;
 
-// color used to draw the player's arrow
+/** color used to draw the player's arrow */
 #define COLOR_PLAYER (PAL8_ORANGE + 1)
-// color for bright map lines (doors, stairs etc.)
+/** color for bright map lines (doors, stairs etc.) */
 #define COLOR_BRIGHT PAL8_YELLOW
-// color for dim map lines/dots
+/** color for dim map lines/dots */
 #define COLOR_DIM (PAL16_YELLOW + 8)
 
 #define MAPFLAG_TYPE 0x000F
-// these are in the second byte
+/** these are in the second byte */
 #define MAPFLAG_VERTDOOR 0x01
 #define MAPFLAG_HORZDOOR 0x02
 #define MAPFLAG_VERTARCH 0x04

Source/automap.h

@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file automap.h
+ *
+ * Interface of the ingame map overlay.
+ */
 #ifndef __AUTOMAP_H__
 #define __AUTOMAP_H__
 

Source/capture.cpp

@@ -1,5 +1,17 @@
+/**
+ * @file capture.cpp
+ *
+ * Implementation of the screenshot function.
+ */
 #include "all.h"
 
+/**
+ * @brief Write the PCX-file header
+ * @param hFile File handler for the PCX file.
+ * @param width Image width
+ * @param height Image height
+ * @return True on success
+ */
 static BOOL CaptureHdr(HANDLE hFile, short width, short height)
 {
 	DWORD lpNumBytes;

Source/capture.h

@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file capture.h
+ *
+ * Interface of the screenshot function.
+ */
 #ifndef __CAPTURE_H__
 #define __CAPTURE_H__
 

Source/codec.cpp

@@ -1,3 +1,8 @@
+/**
+ * @file codec.cpp
+ *
+ * Implementation of save game encryption algorithm.
+ */
 #include "all.h"
 
 struct CodecSignature {

Source/codec.h

@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file codec.h
+ *
+ * Interface of save game encryption algorithm.
+ */
 #ifndef __CODEC_H__
 #define __CODEC_H__
 

Source/control.cpp

@@ -1,3 +1,8 @@
+/**
+ * @file control.cpp
+ *
+ * Implementation of the character and main control panels
+ */
 #include "all.h"
 
 BYTE sgbNextTalkSave;
@@ -18,7 +23,8 @@ BOOL drawmanaflag;
 BOOL chrbtnactive;
 char sgszTalkMsg[MAX_SEND_STR_LEN];
 BYTE *pPanelText;
-int nGoldFrame; /** current frame # for the pentagram caret in gold input */
+/** current frame # for the pentagram caret in gold input */
+int nGoldFrame;
 BYTE *pLifeBuff;
 BYTE *pBtmBuff;
 BYTE *pTalkBtns;
@@ -36,7 +42,8 @@ char tempstr[256];
 BOOLEAN whisper[MAX_PLRS];
 int sbooktab;
 int pSplType;
-int frame; /** current frame # for the pentagram caret in chat input */
+/** current frame # for the pentagram caret in chat input */
+int frame;
 int initialDropGoldIndex;
 BOOL talkflag;
 BYTE *pSBkIconCels;

Source/control.h

@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file control.h
+ *
+ * Interface of the character and main control panels
+ */
 #ifndef __CONTROL_H__
 #define __CONTROL_H__
 

Source/cursor.cpp

@@ -1,3 +1,8 @@
+/**
+ * @file cursor.cpp
+ *
+ * Implementation of cursor tracking functionality.
+ */
 #include "all.h"
 
 int cursH;
@@ -8,7 +13,7 @@ int icursW28;
 BYTE *pCursCels;
 int icursH;
 
-// inv_item value
+/** inv_item value */
 char pcursinvitem;
 int icursW;
 char pcursitem;
@@ -20,6 +25,7 @@ int pcurstemp;
 int pcurs;
 
 /* rdata */
+/** Maps from objcurs.cel frame number to frame width. */
 const int InvItemWidth[180] = {
 	// Cursors
 	0, 33, 32, 32, 32, 32, 32, 32, 32, 32, 32, 23,
@@ -43,6 +49,7 @@ const int InvItemWidth[180] = {
 	2 * 28, 2 * 28, 2 * 28, 2 * 28, 2 * 28, 2 * 28, 2 * 28, 2 * 28
 };
 
+/** Maps from objcurs.cel frame number to frame height. */
 const int InvItemHeight[180] = {
 	// Cursors
 	0, 29, 32, 32, 32, 32, 32, 32, 32, 32, 32, 35,

Source/cursor.h

@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file cursor.h
+ *
+ * Interface of cursor tracking functionality.
+ */
 #ifndef __CURSOR_H__
 #define __CURSOR_H__
 

Source/dead.cpp

@@ -1,6 +1,11 @@
+/**
+ * @file dead.cpp
+ *
+ * Implementation of functions for placing dead monsters.
+ */
 #include "all.h"
 
-// unused, this was probably for blood boil/burn
+/** unused, this was probably for blood boil/burn */
 int spurtndx;
 DeadStruct dead[MAXDEAD];
 int stonendx;

Source/dead.h

@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file dead.h
+ *
+ * Interface of functions for placing dead monsters.
+ */
 #ifndef __DEAD_H__
 #define __DEAD_H__
 

Source/debug.cpp

@@ -1,3 +1,8 @@
+/**
+ * @file debug.cpp
+ *
+ * Implementation of debug functions.
+ */
 #include "all.h"
 
 #ifdef _DEBUG

Source/debug.h

@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file debug.h
+ *
+ * Interface of debug functions.
+ */
 #ifndef __DEBUG_H__
 #define __DEBUG_H__
 

Source/diablo.cpp

@@ -1,3 +1,8 @@
+/**
+ * @file diablo.cpp
+ *
+ * Implementation of the main game initialization functions.
+ */
 #include "all.h"
 #include "../3rdParty/Storm/Source/storm.h"
 #include "../DiabloUI/diabloui.h"
@@ -22,11 +27,13 @@ int DebugMonsters[10];
 BOOLEAN cineflag;
 int force_redraw;
 BOOL visiondebug;
-BOOL scrollflag; /* unused */
+/** unused */
+BOOL scrollflag;
 BOOL light4flag;
 BOOL leveldebug;
 BOOL monstdebug;
-BOOL trigdebug; /* unused */
+/** unused */
+BOOL trigdebug;
 int setseed;
 int debugmonsttypes;
 int PauseMode;
@@ -56,12 +63,14 @@ int framerate;
 int framestart;
 #endif
 BOOL FriendlyMode = TRUE;
+/** Default quick messages */
 char *spszMsgTbl[4] = {
 	"I need help! Come Here!",
 	"Follow me.",
 	"Here's something for you.",
 	"Now you DIE!"
 };
+/** INI files variable names for quick message keys */
 char *spszMsgHotKeyTbl[4] = { "F9", "F10", "F11", "F12" };
 
 void FreeGameMem()
@@ -236,6 +245,13 @@ BOOL diablo_get_not_running()
 	return GetLastError() != ERROR_ALREADY_EXISTS;
 }
 
+/**
+ * @brief Main entry point, check env, initialize systesm, play intros, start main menu, shut down
+ * @param hInstance A handle to the current instance of the application.
+ * @param hPrevInstance Always null
+ * @param lpCmdLine The command line for the application
+ * @param nCmdShow Initial window state
+ */
 int APIENTRY WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow)
 {
 	HINSTANCE hInst;

Source/diablo.h

@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file diablo.h
+ *
+ * Interface of the main game initialization functions.
+ */
 #ifndef __DIABLO_H__
 #define __DIABLO_H__
 
@@ -22,11 +26,13 @@ extern int DebugMonsters[10];
 extern BOOLEAN cineflag;
 extern int force_redraw;
 extern BOOL visiondebug;
-extern BOOL scrollflag; /* unused */
+/** unused */
+extern BOOL scrollflag;
 extern BOOL light4flag;
 extern BOOL leveldebug;
 extern BOOL monstdebug;
-extern BOOL trigdebug; /* unused */
+/** unused */
+extern BOOL trigdebug;
 extern int setseed;
 extern int debugmonsttypes;
 extern int PauseMode;

Source/doom.cpp

@@ -1,3 +1,8 @@
+/**
+ * @file doom.cpp
+ *
+ * Implementation of the map of the stars quest.
+ */
 #include "all.h"
 
 int doom_quest_time;

Source/doom.h

@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file doom.h
+ *
+ * Interface of the map of the stars quest.
+ */
 #ifndef __DOOM_H__
 #define __DOOM_H__
 

Source/drlg_l1.cpp

@@ -1,3 +1,8 @@
+/**
+ * @file drlg_l1.cpp
+ *
+ * Implementation of the cathedral level generation algorithms.
+ */
 #include "all.h"
 
 BYTE L5dungeon[80][80];

Source/drlg_l1.h

@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file drlg_l1.h
+ *
+ * Interface of the cathedral level generation algorithms.
+ */
 #ifndef __DRLG_L1_H__
 #define __DRLG_L1_H__