diff --git a/.gitignore b/.gitignore
index d14076ae..97e810c1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -373,3 +373,4 @@ ASALocalRun/
 *.pubxml.user
 
 # End of https://www.gitignore.io/api/visualstudio
+/docs/html/
diff --git a/Source/all.h b/Source/all.h
index 4a19fbbf..75e22931 100644
--- a/Source/all.h
+++ b/Source/all.h
@@ -1,3 +1,8 @@
+/**
+ * @file all.h
+ *
+ * Include all aplication headers.
+ */
 #ifndef __ALL_H__
 #define __ALL_H__
 
diff --git a/Source/appfat.cpp b/Source/appfat.cpp
index 51be3e1d..69222e70 100644
--- a/Source/appfat.cpp
+++ b/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;
diff --git a/Source/appfat.h b/Source/appfat.h
index 97c49825..ea335f09 100644
--- a/Source/appfat.h
+++ b/Source/appfat.h
@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file appfat.h
+ *
+ * Interface of error dialogs.
+ */
 #ifndef __APPFAT_H__
 #define __APPFAT_H__
 
diff --git a/Source/automap.cpp b/Source/automap.cpp
index 5a2df7ab..6f64b069 100644
--- a/Source/automap.cpp
+++ b/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
diff --git a/Source/automap.h b/Source/automap.h
index a947c467..22ccfaa7 100644
--- a/Source/automap.h
+++ b/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__
 
diff --git a/Source/capture.cpp b/Source/capture.cpp
index ce3a07bf..552b43e2 100644
--- a/Source/capture.cpp
+++ b/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;
diff --git a/Source/capture.h b/Source/capture.h
index c1e86c10..9a54e2d1 100644
--- a/Source/capture.h
+++ b/Source/capture.h
@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file capture.h
+ *
+ * Interface of the screenshot function.
+ */
 #ifndef __CAPTURE_H__
 #define __CAPTURE_H__
 
diff --git a/Source/codec.cpp b/Source/codec.cpp
index 835cf447..1e9402b7 100644
--- a/Source/codec.cpp
+++ b/Source/codec.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file codec.cpp
+ *
+ * Implementation of save game encryption algorithm.
+ */
 #include "all.h"
 
 struct CodecSignature {
diff --git a/Source/codec.h b/Source/codec.h
index 0cae2784..00c11cea 100644
--- a/Source/codec.h
+++ b/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__
 
diff --git a/Source/control.cpp b/Source/control.cpp
index 589efcfb..d612b2b3 100644
--- a/Source/control.cpp
+++ b/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;
diff --git a/Source/control.h b/Source/control.h
index 1e64e1fa..0fa12609 100644
--- a/Source/control.h
+++ b/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__
 
diff --git a/Source/cursor.cpp b/Source/cursor.cpp
index d463c15a..8fa3aa31 100644
--- a/Source/cursor.cpp
+++ b/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,
diff --git a/Source/cursor.h b/Source/cursor.h
index 5fbb4241..42b1df21 100644
--- a/Source/cursor.h
+++ b/Source/cursor.h
@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file cursor.h
+ *
+ * Interface of cursor tracking functionality.
+ */
 #ifndef __CURSOR_H__
 #define __CURSOR_H__
 
diff --git a/Source/dead.cpp b/Source/dead.cpp
index 00e87d27..ba72cd0a 100644
--- a/Source/dead.cpp
+++ b/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;
diff --git a/Source/dead.h b/Source/dead.h
index bc16374d..f9e992a2 100644
--- a/Source/dead.h
+++ b/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__
 
diff --git a/Source/debug.cpp b/Source/debug.cpp
index f01542c6..24d004d0 100644
--- a/Source/debug.cpp
+++ b/Source/debug.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file debug.cpp
+ *
+ * Implementation of debug functions.
+ */
 #include "all.h"
 
 #ifdef _DEBUG
diff --git a/Source/debug.h b/Source/debug.h
index d3dacf70..439fc9c8 100644
--- a/Source/debug.h
+++ b/Source/debug.h
@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file debug.h
+ *
+ * Interface of debug functions.
+ */
 #ifndef __DEBUG_H__
 #define __DEBUG_H__
 
diff --git a/Source/diablo.cpp b/Source/diablo.cpp
index 8b97a5d8..c764276d 100644
--- a/Source/diablo.cpp
+++ b/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;
diff --git a/Source/diablo.h b/Source/diablo.h
index 8127673e..1e3f5002 100644
--- a/Source/diablo.h
+++ b/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;
diff --git a/Source/doom.cpp b/Source/doom.cpp
index b336849e..b419c702 100644
--- a/Source/doom.cpp
+++ b/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;
diff --git a/Source/doom.h b/Source/doom.h
index 31635fe0..b72b2c33 100644
--- a/Source/doom.h
+++ b/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__
 
diff --git a/Source/drlg_l1.cpp b/Source/drlg_l1.cpp
index 64391da7..9aa56141 100644
--- a/Source/drlg_l1.cpp
+++ b/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];
diff --git a/Source/drlg_l1.h b/Source/drlg_l1.h
index e9e354d5..2b0ff6c5 100644
--- a/Source/drlg_l1.h
+++ b/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__
 
diff --git a/Source/drlg_l2.cpp b/Source/drlg_l2.cpp
index b66ccab9..fc3ea922 100644
--- a/Source/drlg_l2.cpp
+++ b/Source/drlg_l2.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file drlg_l2.cpp
+ *
+ * Implementation of the catacombs level generation algorithms.
+ */
 #ifndef SPAWN
 #include "all.h"
 
diff --git a/Source/drlg_l2.h b/Source/drlg_l2.h
index 35beda6b..8b9e8690 100644
--- a/Source/drlg_l2.h
+++ b/Source/drlg_l2.h
@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file drlg_l2.h
+ *
+ * Interface of the catacombs level generation algorithms.
+ */
 #ifndef __DRLG_L2_H__
 #define __DRLG_L2_H__
 
diff --git a/Source/drlg_l3.cpp b/Source/drlg_l3.cpp
index 43a1a67e..3679c2e4 100644
--- a/Source/drlg_l3.cpp
+++ b/Source/drlg_l3.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file drlg_l3.cpp
+ *
+ * Implementation of the caves level generation algorithms.
+ */
 #ifndef SPAWN
 #include "all.h"
 
diff --git a/Source/drlg_l3.h b/Source/drlg_l3.h
index 9170d7f9..a3067300 100644
--- a/Source/drlg_l3.h
+++ b/Source/drlg_l3.h
@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file drlg_l3.h
+ *
+ * Interface of the caves level generation algorithms.
+ */
 #ifndef __DRLG_L3_H__
 #define __DRLG_L3_H__
 
diff --git a/Source/drlg_l4.cpp b/Source/drlg_l4.cpp
index 9cf009bf..f97a0be4 100644
--- a/Source/drlg_l4.cpp
+++ b/Source/drlg_l4.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file drlg_l4.cpp
+ *
+ * Implementation of the hell level generation algorithms.
+ */
 #include "all.h"
 
 int diabquad1x;
diff --git a/Source/drlg_l4.h b/Source/drlg_l4.h
index 6559545b..cf64e917 100644
--- a/Source/drlg_l4.h
+++ b/Source/drlg_l4.h
@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file drlg_l4.h
+ *
+ * Interface of the hell level generation algorithms.
+ */
 #ifndef __DRLG_L4_H__
 #define __DRLG_L4_H__
 
diff --git a/Source/dthread.cpp b/Source/dthread.cpp
index b17457cf..6e3e9a0b 100644
--- a/Source/dthread.cpp
+++ b/Source/dthread.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file dthread.cpp
+ *
+ * Implementation of functions for updating game state from network commands.
+ */
 #include "all.h"
 #include "../3rdParty/Storm/Source/storm.h"
 
diff --git a/Source/dthread.h b/Source/dthread.h
index 4ad5d3fb..7a9e86c9 100644
--- a/Source/dthread.h
+++ b/Source/dthread.h
@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file dthread.h
+ *
+ * Interface of functions for updating game state from network commands.
+ */
 #ifndef __DTHREAD_H__
 #define __DTHREAD_H__
 
diff --git a/Source/dx.cpp b/Source/dx.cpp
index 99c5dc33..2ead8b68 100644
--- a/Source/dx.cpp
+++ b/Source/dx.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file dx.cpp
+ *
+ * Implementation of functions setting up the graphics pipeline.
+ */
 #include "all.h"
 #include "../3rdParty/Storm/Source/storm.h"
 
diff --git a/Source/dx.h b/Source/dx.h
index 39c0fbef..1a13e3b1 100644
--- a/Source/dx.h
+++ b/Source/dx.h
@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file dx.h
+ *
+ * Interface of functions setting up the graphics pipeline.
+ */
 #ifndef __DX_H__
 #define __DX_H__
 
diff --git a/Source/effects.cpp b/Source/effects.cpp
index 0afb731a..cfa3d203 100644
--- a/Source/effects.cpp
+++ b/Source/effects.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file effects.cpp
+ *
+ * Implementation of functions for loading and playing sounds.
+ */
 #include "all.h"
 #include "../3rdParty/Storm/Source/storm.h"
 
@@ -6,10 +11,17 @@ int sfxdnum;
 HANDLE sfx_stream;
 TSFX *sfx_data_cur;
 
+/**
+ * Monster sound type prefix
+ * a: Attack
+ * h: Hit
+ * d: Death
+ * s: Special
+ */
 const char MonstSndChar[] = { 'a', 'h', 'd', 's' };
 
 /* data */
-
+/** List of all sounds, except monsters and music */
 TSFX sgSFX[] = {
 	// clang-format off
 	// bFlags,                   pszName,                       pSnd
diff --git a/Source/effects.h b/Source/effects.h
index 8ed845e6..5aa3ddbc 100644
--- a/Source/effects.h
+++ b/Source/effects.h
@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file effects.h
+ *
+ * Interface of functions for loading and playing sounds.
+ */
 #ifndef __EFFECTS_H__
 #define __EFFECTS_H__
 
diff --git a/Source/encrypt.cpp b/Source/encrypt.cpp
index 50abc783..dd4d0a4a 100644
--- a/Source/encrypt.cpp
+++ b/Source/encrypt.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file encrypt.cpp
+ *
+ * Implementation of functions for compression and decompressing MPQ data.
+ */
 #include "all.h"
 #include "../3rdParty/PKWare/pkware.h"
 
diff --git a/Source/encrypt.h b/Source/encrypt.h
index 0d76b0f8..552bed22 100644
--- a/Source/encrypt.h
+++ b/Source/encrypt.h
@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file encrypt.h
+ *
+ * Interface of functions for compression and decompressing MPQ data.
+ */
 #ifndef __ENCRYPT_H__
 #define __ENCRYPT_H__
 
diff --git a/Source/engine.cpp b/Source/engine.cpp
index 13a86bfc..fb460826 100644
--- a/Source/engine.cpp
+++ b/Source/engine.cpp
@@ -1,3 +1,15 @@
+/**
+ * @file engine.cpp
+ *
+ * Implementation of basic engine helper functions:
+ * - Sprite blitting
+ * - Drawing
+ * - Angle calculation
+ * - RNG
+ * - Memory allocation
+ * - File loading
+ * - Video playback
+ */
 #include "all.h"
 #include "../3rdParty/Storm/Source/storm.h"
 
@@ -8,7 +20,9 @@
 char gbPixelCol;  // automap pixel color 8-bit (palette entry)
 BOOL gbRotateMap; // flip - if y < x
 int orgseed;
+/** Width of sprite being blitted */
 int sgnWidth;
+/** Current game seed */
 int sglGameSeed;
 #ifdef __cplusplus
 static CCritSect sgMemCrit;
@@ -2255,12 +2269,14 @@ void engine_draw_pixel(int sx, int sy)
 #endif
 }
 
+/** Macro used in DrawLine() */
 #define GG_SWAP(A, B) \
 	{                 \
 		(A) ^= (B);   \
 		(B) ^= (A);   \
 		(A) ^= (B);   \
 	}
+/** Macro used in DrawLine() */
 #define GG_ABSOLUTE(I, J, K) (((I) - (J)) * ((K) = (((I) - (J)) < 0 ? -1 : 1)))
 
 /**
diff --git a/Source/engine.h b/Source/engine.h
index 26075080..9027445b 100644
--- a/Source/engine.h
+++ b/Source/engine.h
@@ -1,15 +1,31 @@
-//HEADER_GOES_HERE
+/**
+ * @file engine.h
+ *
+ *  of basic engine helper functions:
+ * - Sprite blitting
+ * - Drawing
+ * - Angle calculation
+ * - RNG
+ * - Memory allocation
+ * - File loading
+ * - Video playback
+ */
 #ifndef __ENGINE_H__
 #define __ENGINE_H__
 
 //offset 0
 //pCelBuff->pFrameTable[0]
 
-extern char gbPixelCol;  // automap pixel color 8-bit (palette entry)
-extern BOOL gbRotateMap; // flip - if y < x
+/** automap pixel color 8-bit (palette entry) */
+extern char gbPixelCol;
+/** flip - if y < x */
+extern BOOL gbRotateMap;
+/** Seed value before the most recent call to SetRndSeed() */
 extern int orgseed;
+/** Track number of calls to GetRndSeed() since last call to SetRndSeed() */
 extern int SeedCount;
-extern BOOL gbNotInView; // valid - if x/y are in bounds
+/** valid - if x/y are in bounds */
+extern BOOL gbNotInView;
 
 __FINLINE BYTE *CelGetFrame(BYTE *pCelBuff, int nCel, int *nDataSize);
 
diff --git a/Source/error.cpp b/Source/error.cpp
index 1d96d370..2df97ac3 100644
--- a/Source/error.cpp
+++ b/Source/error.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file error.cpp
+ *
+ * Implementation of in-game message functions.
+ */
 #include "all.h"
 
 char msgtable[MAX_SEND_STR_LEN];
@@ -5,6 +10,7 @@ char msgdelay;
 char msgflag;
 char msgcnt;
 
+/** Maps from error_id to error message. */
 char *MsgStrings[44] = {
 	"",
 	"No automap available in town",
diff --git a/Source/error.h b/Source/error.h
index 4191582a..046307b8 100644
--- a/Source/error.h
+++ b/Source/error.h
@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file error.h
+ *
+ * Interface of in-game message functions.
+ */
 #ifndef __ERROR_H__
 #define __ERROR_H__
 
diff --git a/Source/fault.cpp b/Source/fault.cpp
index 64d2f5d8..43e14f5e 100644
--- a/Source/fault.cpp
+++ b/Source/fault.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file fault.cpp
+ *
+ * Implementation of exception logging functionality.
+ */
 #include "all.h"
 
 LPTOP_LEVEL_EXCEPTION_FILTER lpTopLevelExceptionFilter;
diff --git a/Source/fault.h b/Source/fault.h
index 0dc743cb..4ed85ea1 100644
--- a/Source/fault.h
+++ b/Source/fault.h
@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file fault.h
+ *
+ * Interface of exception logging functionality.
+ */
 #ifndef __FAULT_H__
 #define __FAULT_H__
 
diff --git a/Source/gamemenu.cpp b/Source/gamemenu.cpp
index 7cf3db3c..2e385b0b 100644
--- a/Source/gamemenu.cpp
+++ b/Source/gamemenu.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file gamemenu.cpp
+ *
+ * Implementation of the ingame menu functions.
+ */
 #include "all.h"
 
 TMenuItem sgSingleMenu[6] = {
diff --git a/Source/gamemenu.h b/Source/gamemenu.h
index 634e17cf..a6ad2f1c 100644
--- a/Source/gamemenu.h
+++ b/Source/gamemenu.h
@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file gamemenu.h
+ *
+ * Interface of the ingame menu functions.
+ */
 #ifndef __GAMEMENU_H__
 #define __GAMEMENU_H__
 
diff --git a/Source/gmenu.cpp b/Source/gmenu.cpp
index d78cd99f..c13c7676 100644
--- a/Source/gmenu.cpp
+++ b/Source/gmenu.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file gmenu.cpp
+ *
+ * Implementation of the ingame navigation and interaction.
+ */
 #include "all.h"
 
 BYTE *optbar_cel;
@@ -13,6 +18,7 @@ BYTE *option_cel;
 BYTE *sgpLogo;
 int sgCurrentMenuIdx;
 
+/** Maps from font index to bigtgold.cel frame number. */
 const BYTE lfontframe[127] = {
 	0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
 	0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
@@ -28,6 +34,7 @@ const BYTE lfontframe[127] = {
 	14, 15, 16, 17, 18, 19, 20, 21, 22, 23,
 	24, 25, 26, 20, 0, 21, 0
 };
+/* Maps from bigtgold.cel frame number to character width. */
 const BYTE lfontkern[56] = {
 	18, 33, 21, 26, 28, 19, 19, 26, 25, 11,
 	12, 25, 19, 34, 28, 32, 20, 32, 28, 20,
diff --git a/Source/gmenu.h b/Source/gmenu.h
index b884a9a9..1d0490d3 100644
--- a/Source/gmenu.h
+++ b/Source/gmenu.h
@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file gmenu.h
+ *
+ * Interface of the ingame navigation and interaction.
+ */
 #ifndef __GMENU_H__
 #define __GMENU_H__
 
diff --git a/Source/interfac.cpp b/Source/interfac.cpp
index e3b3ebd1..be837929 100644
--- a/Source/interfac.cpp
+++ b/Source/interfac.cpp
@@ -5,7 +5,9 @@ void *sgpBackCel;
 int sgdwProgress;
 int progress_id;
 
+/** The colour used for the progress bar as an index into the palette. */
 const BYTE BarColor[3] = { 138, 43, 254 };
+/** The screen position of the top left corner of the progress bar. */
 const int BarPos[3][2] = { { 53, 37 }, { 53, 421 }, { 53, 37 } };
 
 void interface_msg_pump()
diff --git a/Source/lighting.cpp b/Source/lighting.cpp
index 51b8edaa..adde0a7f 100644
--- a/Source/lighting.cpp
+++ b/Source/lighting.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file lighting.cpp
+ *
+ * Implementation of light and vision.
+ */
 #include "all.h"
 
 LightListStruct VisionList[MAXVISION];
@@ -401,9 +406,7 @@ 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,
@@ -425,9 +428,7 @@ char *pCrawlTable[19] = {
 	CrawlTable + 2187,
 	CrawlTable + 2460
 };
-/**
- * vCrawlTable specifies the X- Y-coordinate offsets of lighting visions.
- */
+/** 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 },
@@ -453,31 +454,29 @@ BYTE vCrawlTable[23][30] = {
 	{ 0, 1, 0, 2, 0, 3, 0, 4, 0, 5, 0, 6, 0, 7, 1, 8, 1, 9, 1, 10, 1, 11, 1, 12, 1, 13, 1, 14, 1, 15 },
 	{ 0, 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 }
 };
-BYTE byte_49463C[18][18] = /* unused */
-    {
-	    { 0, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3 },
-	    { 0, 1, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3 },
-	    { 0, 1, 2, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3 },
-	    { 0, 0, 1, 2, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3 },
-	    { 0, 0, 1, 1, 2, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3 },
-	    { 0, 0, 1, 1, 2, 2, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3 },
-	    { 0, 0, 0, 1, 1, 2, 2, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3 },
-	    { 0, 0, 0, 1, 1, 1, 2, 2, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3 },
-	    { 0, 0, 0, 0, 1, 1, 2, 2, 2, 3, 3, 3, 3, 3, 3, 3, 3, 3 },
-	    { 0, 0, 0, 0, 1, 1, 1, 2, 2, 2, 3, 3, 3, 3, 3, 3, 3, 3 },
-	    { 0, 0, 0, 0, 0, 1, 1, 1, 2, 2, 2, 3, 3, 3, 3, 3, 3, 3 },
-	    { 0, 0, 0, 0, 0, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 3, 3 },
-	    { 0, 0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 3 },
-	    { 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3 },
-	    { 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 3, 3 },
-	    { 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 3, 3 },
-	    { 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 3 },
-	    { 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2 }
-    };
+/** unused */
+BYTE byte_49463C[18][18] = {
+	{ 0, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3 },
+	{ 0, 1, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3 },
+	{ 0, 1, 2, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3 },
+	{ 0, 0, 1, 2, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3 },
+	{ 0, 0, 1, 1, 2, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3 },
+	{ 0, 0, 1, 1, 2, 2, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3 },
+	{ 0, 0, 0, 1, 1, 2, 2, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3 },
+	{ 0, 0, 0, 1, 1, 1, 2, 2, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3 },
+	{ 0, 0, 0, 0, 1, 1, 2, 2, 2, 3, 3, 3, 3, 3, 3, 3, 3, 3 },
+	{ 0, 0, 0, 0, 1, 1, 1, 2, 2, 2, 3, 3, 3, 3, 3, 3, 3, 3 },
+	{ 0, 0, 0, 0, 0, 1, 1, 1, 2, 2, 2, 3, 3, 3, 3, 3, 3, 3 },
+	{ 0, 0, 0, 0, 0, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 3, 3 },
+	{ 0, 0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 3 },
+	{ 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3 },
+	{ 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 3, 3 },
+	{ 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 3, 3 },
+	{ 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 3 },
+	{ 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.
- */
+/** 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/lighting.h b/Source/lighting.h
index 5b593423..ac4b1278 100644
--- a/Source/lighting.h
+++ b/Source/lighting.h
@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file lighting.h
+ *
+ * Interface of light and vision.
+ */
 #ifndef __LIGHTING_H__
 #define __LIGHTING_H__
 
diff --git a/Source/list.h b/Source/list.h
index 154f9bec..7a2c35fc 100644
--- a/Source/list.h
+++ b/Source/list.h
@@ -1,4 +1,6 @@
-/* Intrusive double-linked list implementation,
+/**
+ * @file list.h
+ * Intrusive double-linked list implementation,
  * based on https://github.com/webcoyote/coho/blob/master/Base/List.h
  */
 
@@ -7,22 +9,22 @@
 #define OBJECT_NAME(obj) (((const char *)&typeid(obj)) + 8)
 
 /******************************************************************************
-*
-*   List definition macros
-*
-***/
+ *
+ *   List definition macros
+ *
+ ***/
 
-// Define a field within a structure that will be used to link it into a list
+/** Define a field within a structure that will be used to link it into a list */
 #define LIST_LINK(T) TLink<T>
 
 template <class T>
 class TLink;
 
 /******************************************************************************
-*
-*   TList
-*
-***/
+ *
+ *   TList
+ *
+ ***/
 
 //=============================================================================
 template <class T>
@@ -159,10 +161,10 @@ void TList<T>::UnlinkAll()
 }
 
 /******************************************************************************
-*
-*   TLink
-*
-***/
+ *
+ *   TLink
+ *
+ ***/
 
 //=============================================================================
 template <class T>
diff --git a/Source/logging.cpp b/Source/logging.cpp
index c0ea8a7c..cffa639e 100644
--- a/Source/logging.cpp
+++ b/Source/logging.cpp
@@ -11,7 +11,9 @@ DWORD nNumberOfBytesToWrite;
 
 /* data */
 
+/** Has the log file not yet been created. */
 BOOL log_not_created = TRUE;
+/** Handle to the log file. */
 HANDLE log_file = INVALID_HANDLE_VALUE;
 
 void __cdecl log_flush(BOOL force_close)
diff --git a/Source/mainmenu.cpp b/Source/mainmenu.cpp
index 1c66f703..d9eec335 100644
--- a/Source/mainmenu.cpp
+++ b/Source/mainmenu.cpp
@@ -6,6 +6,7 @@ char gszHero[16];
 
 /* data */
 
+/** The active music track id for the main menu. */
 int menu_music_track_id = TMUSIC_INTRO;
 
 void mainmenu_refresh_music()
diff --git a/Source/misdat.cpp b/Source/misdat.cpp
index 6449e655..49cc1034 100644
--- a/Source/misdat.cpp
+++ b/Source/misdat.cpp
@@ -1,5 +1,6 @@
 #include "all.h"
 
+/** Data related to each missile ID. */
 MissileData missiledata[] = {
 	// clang-format off
 	// mName,             mAddProc,          mProc,             mDraw, mType, mResist,        mFileNum,       miSFX,       mlSFX;
@@ -74,6 +75,7 @@ MissileData missiledata[] = {
 	// clang-format on
 };
 
+/** Data related to each missile graphic ID. */
 MisFileData misfiledata[] = {
 	// clang-format off
 	// mAnimName, mAnimFAmt, mName, mFlags, mAnimData[16],                                      mAnimDelay[16],                                     mAnimLen[16],                                                       mAnimWidth[16],                                                             mAnimWidth2[16]
diff --git a/Source/missiles.cpp b/Source/missiles.cpp
index 96910d80..517b2ac2 100644
--- a/Source/missiles.cpp
+++ b/Source/missiles.cpp
@@ -9,7 +9,9 @@ ChainStruct chain[MAXMISSILES];
 BOOL MissilePreFlag;
 int numchains;
 
+/** Maps from direction to X-offset. */
 int XDirAdd[8] = { 1, 0, -1, -1, -1, 0, 1, 1 };
+/** Maps from direction to Y-offset. */
 int YDirAdd[8] = { 1, 1, 1, 0, -1, -1, -1, 0 };
 
 void GetDamageAmt(int i, int *mind, int *maxd)
diff --git a/Source/monster.cpp b/Source/monster.cpp
index 924ba107..cf1e1ac9 100644
--- a/Source/monster.cpp
+++ b/Source/monster.cpp
@@ -1,7 +1,12 @@
+/**
+ * @file monster.cpp
+ *
+ * Implementation of monster functionality, AI, actions, spawning, loading, etc.
+ */
 #include "all.h"
 #include "../3rdParty/Storm/Source/storm.h"
 
-// Tracks which missile files are already loaded
+/** Tracks which missile files are already loaded */
 int MissileFileFlag;
 
 // BUGFIX: replace monstkills[MAXMONSTERS] with monstkills[NUM_MTYPES].
@@ -54,7 +59,7 @@ int opposite[8] = { 4, 5, 6, 7, 0, 1, 2, 3 };
 int offset_x[8] = { 1, 0, -1, -1, -1, 0, 1, 1 };
 int offset_y[8] = { 1, 1, 1, 0, -1, -1, -1, 0 };
 
-/* unused */
+/** unused */
 int rnd5[4] = { 5, 10, 15, 20 };
 int rnd10[4] = { 10, 15, 20, 30 };
 int rnd20[4] = { 20, 30, 40, 50 };
diff --git a/Source/monster.h b/Source/monster.h
index 45d884df..881e4cab 100644
--- a/Source/monster.h
+++ b/Source/monster.h
@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file monster.h
+ *
+ * Interface of monster functionality, AI, actions, spawning, loading, etc.
+ */
 #ifndef __MONSTER_H__
 #define __MONSTER_H__
 
@@ -174,7 +178,7 @@ extern int opposite[8];
 extern int offset_x[8];
 extern int offset_y[8];
 
-/* unused */
+/** unused */
 extern int rnd5[4];
 extern int rnd10[4];
 extern int rnd20[4];
diff --git a/Source/movie.cpp b/Source/movie.cpp
index 40c513c3..75fb4791 100644
--- a/Source/movie.cpp
+++ b/Source/movie.cpp
@@ -1,7 +1,9 @@
 #include "all.h"
 #include "../3rdParty/Storm/Source/storm.h"
 
+/** Should the movie continue playing. */
 BYTE movie_playing;
+/** Should the movie play in a loop. */
 BOOL loop_movie;
 
 void play_movie(char *pszMovie, BOOL user_can_close)
diff --git a/Source/mpqapi.cpp b/Source/mpqapi.cpp
index 985eb25b..2bdcbfc6 100644
--- a/Source/mpqapi.cpp
+++ b/Source/mpqapi.cpp
@@ -4,8 +4,10 @@
 DWORD sgdwMpqOffset;
 char mpq_buf[4096];
 _HASHENTRY *sgpHashTbl;
+/** Has the savegame-file been modified in memory. */
 BOOL save_archive_modified;
 _BLOCKENTRY *sgpBlockTbl;
+/** Is the savegame-file currently open. */
 BOOLEAN save_archive_open;
 
 //note: 32872 = 32768 + 104 (sizeof(_FILEHEADER))
diff --git a/Source/nthread.cpp b/Source/nthread.cpp
index 4911067a..ec5d75bd 100644
--- a/Source/nthread.cpp
+++ b/Source/nthread.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file nthread.cpp
+ *
+ * Implementation of functions for managing game ticks.
+ */
 #include "all.h"
 #include "../3rdParty/Storm/Source/storm.h"
 
diff --git a/Source/nthread.h b/Source/nthread.h
index 84263e95..98b50121 100644
--- a/Source/nthread.h
+++ b/Source/nthread.h
@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file nthread.h
+ *
+ * Interface of functions for managing game ticks.
+ */
 #ifndef __NTHREAD_H__
 #define __NTHREAD_H__
 
diff --git a/Source/objects.cpp b/Source/objects.cpp
index 07b3a32e..5f3c8126 100644
--- a/Source/objects.cpp
+++ b/Source/objects.cpp
@@ -52,7 +52,7 @@ char shrinemax[NUM_SHRINETYPE] = {
 	16, 16, 16, 16, 16, 16, 16, 16, 16, 16,
 	16, 16, 16, 16, 16, 16
 };
-// 0 - sp+mp, 1 - sp only, 2 - mp only
+/** 0 - sp+mp, 1 - sp only, 2 - mp only */
 BYTE shrineavail[NUM_SHRINETYPE] = {
 	0, 0, 1, 1, 0, 0, 0, 0, 1, 0,
 	0, 0, 0, 0, 0, 0, 0, 0, 2, 0,
diff --git a/Source/pack.cpp b/Source/pack.cpp
index 2ebe3946..931a1c0c 100644
--- a/Source/pack.cpp
+++ b/Source/pack.cpp
@@ -106,8 +106,14 @@ void PackPlayer(PkPlayerStruct *pPack, int pnum, BOOL manashield)
 		pPack->pManaShield = FALSE;
 }
 
-// Note: last slot of item[MAXITEMS+1] used as temporary buffer
-// find real name reference below, possibly [sizeof(item[])/sizeof(ItemStruct)]
+/**
+ * Expand a PkItemStruct in to a ItemStruct
+ *
+ * Note: last slot of item[MAXITEMS+1] used as temporary buffer
+ * find real name reference below, possibly [sizeof(item[])/sizeof(ItemStruct)]
+ * @param is The source packed item
+ * @param id The distination item
+ */
 static void UnPackItem(PkItemStruct *is, ItemStruct *id)
 {
 	if (is->idx == 0xFFFF) {
diff --git a/Source/path.cpp b/Source/path.cpp
index d0dd05d7..0dda4826 100644
--- a/Source/path.cpp
+++ b/Source/path.cpp
@@ -1,30 +1,37 @@
+/**
+ * @file path.cpp
+ *
+ * Implementation of the path finding algorithms.
+ */
 #include "all.h"
 
-// preallocated nodes, search is terminated after 300 nodes are visited
+/** Notes visisted by the path finding algorithm. */
 PATHNODE path_nodes[MAXPATHNODES];
-// size of the pnode_tblptr stack
+/** size of the pnode_tblptr stack */
 int gdwCurPathStep;
-// the number of in-use nodes in path_nodes
+/** the number of in-use nodes in path_nodes */
 int gdwCurNodes;
-/* for reconstructing the path after the A* search is done. The longest
+/**
+ * for reconstructing the path after the A* search is done. The longest
  * possible path is actually 24 steps, even though we can fit 25
  */
 int pnode_vals[MAX_PATH_LENGTH];
-// a linked list of all visited nodes
+/** A linked list of all visited nodes */
 PATHNODE *pnode_ptr;
-// a stack for recursively searching nodes
+/** A stack for recursively searching nodes */
 PATHNODE *pnode_tblptr[MAXPATHNODES];
-// a linked list of the A* frontier, sorted by distance
+/** A linked list of the A* frontier, sorted by distance */
 PATHNODE *path_2_nodes;
 PATHNODE path_unusednodes[MAXPATHNODES];
 
-// for iterating over the 8 possible movement directions
+/** For iterating over the 8 possible movement directions */
 const char pathxdir[8] = { -1, -1, 1, 1, -1, 0, 1, 0 };
 const char pathydir[8] = { -1, 1, -1, 1, 0, -1, 0, 1 };
 
 /* data */
 
-/* each step direction is assigned a number like this:
+/**
+ * each step direction is assigned a number like this:
  *       dx
  *     -1 0 1
  *     +-----
diff --git a/Source/path.h b/Source/path.h
index ff333084..83191d34 100644
--- a/Source/path.h
+++ b/Source/path.h
@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file path.h
+ *
+ * Interface of the path finding algorithms.
+ */
 #ifndef __PATH_H__
 #define __PATH_H__
 
diff --git a/Source/pfile.cpp b/Source/pfile.cpp
index 9fea06a5..d6ac5fa0 100644
--- a/Source/pfile.cpp
+++ b/Source/pfile.cpp
@@ -10,6 +10,7 @@
 #define PASSWORD_MULTI "szqnlsk1"
 #endif
 
+/** List of character names for the character selection screen. */
 static char hero_names[MAX_CHARACTERS][PLR_NAME_LEN];
 BOOL gbValidSaveFile;
 
diff --git a/Source/player.cpp b/Source/player.cpp
index bef128d7..c4913c3f 100644
--- a/Source/player.cpp
+++ b/Source/player.cpp
@@ -42,7 +42,7 @@ int PWVel[3][3] = {
 	{ 2048, 1024, 512 },
 	{ 2048, 1024, 512 }
 };
-// Total number of frames in walk animation.
+/** Total number of frames in walk animation. */
 int AnimLenFromClass[3] = {
 	8, 8, 8
 };
diff --git a/Source/plrmsg.cpp b/Source/plrmsg.cpp
index c5b85113..d745df86 100644
--- a/Source/plrmsg.cpp
+++ b/Source/plrmsg.cpp
@@ -3,6 +3,7 @@
 static BYTE plr_msg_slot;
 _plrmsg plr_msgs[PMSG_COUNT];
 
+/** Maps from player_num to text colour, as used in chat messages. */
 const char text_color_from_player_num[MAX_PLRS + 1] = { COL_WHITE, COL_WHITE, COL_WHITE, COL_WHITE, COL_GOLD };
 
 void plrmsg_delay(BOOL delay)
diff --git a/Source/portal.cpp b/Source/portal.cpp
index 038c33d8..88df7ac7 100644
--- a/Source/portal.cpp
+++ b/Source/portal.cpp
@@ -1,9 +1,13 @@
 #include "all.h"
 
+/** In-game state of portals. */
 PortalStruct portal[MAXPORTAL];
+/** Current portal number (a portal array index). */
 int portalindex;
 
+/** X-coordinate of each players portal in town. */
 int WarpDropX[MAXPORTAL] = { 57, 59, 61, 63 };
+/** Y-coordinate of each players portal in town. */
 int WarpDropY[MAXPORTAL] = { 40, 40, 40, 40 };
 
 void InitPortals()
diff --git a/Source/render.cpp b/Source/render.cpp
index 39a22cb3..7d1327f9 100644
--- a/Source/render.cpp
+++ b/Source/render.cpp
@@ -84,7 +84,7 @@ int WorldTbl3x16[48] = {
 	60, 60, 60
 };
 
-// slope/angle tables, left and right
+/** slope/angle tables, left and right */
 int WorldTbl17_1[17] = { 0, 4, 8, 16, 24, 36, 48, 64, 80, 100, 120, 144, 168, 196, 224, 256, 288 };
 int WorldTbl17_2[17] = { 0, 32, 60, 88, 112, 136, 156, 176, 192, 208, 220, 232, 240, 248, 252, 256, 288 };
 
diff --git a/Source/setmaps.cpp b/Source/setmaps.cpp
index 51b0a345..3a0b8735 100644
--- a/Source/setmaps.cpp
+++ b/Source/setmaps.cpp
@@ -54,6 +54,7 @@ BYTE SkelChamTrans3[36] = {
 	50, 43, 59, 51
 };
 
+/** Maps from quest level to quest level names. */
 char *quest_level_names[] = {
 	"",
 	"Skeleton King's Lair",
diff --git a/Source/spelldat.cpp b/Source/spelldat.cpp
index 8337d598..ce198eaf 100644
--- a/Source/spelldat.cpp
+++ b/Source/spelldat.cpp
@@ -1,5 +1,6 @@
 #include "all.h"
 
+/** Data related to each spell ID. */
 SpellData spelldata[MAX_SPELLS] = {
 	// clang-format off
 	// sName,    sManaCost, sType,           sNameText,         sSkillText, sBookLvl, sStaffLvl, sTargeted, sTownSpell, sMinInt, sSFX,     sMissiles[3],                      sManaAdj, sMinMana, sStaffMin, sStaffMax, sBookCost, sStaffCost
diff --git a/Source/stores.cpp b/Source/stores.cpp
index 61d3dd7d..5bb86f53 100644
--- a/Source/stores.cpp
+++ b/Source/stores.cpp
@@ -60,6 +60,7 @@ int SStringY[24] = {
 	264,
 	276
 };
+/** Maps from towner IDs to NPC names. */
 char *talkname[9] = {
 	"Griswold",
 	"Pepin",
diff --git a/Source/textdat.cpp b/Source/textdat.cpp
index b3432759..dbf7898a 100644
--- a/Source/textdat.cpp
+++ b/Source/textdat.cpp
@@ -784,4 +784,5 @@ const TextDataStruct alltext[] = {
 	{ "Thank goodness you've returned!\nMuch has changed since you lived here, my friend. All was peaceful until the dark riders came and destroyed our village. Many were cut down where they stood, and those who took up arms were slain or dragged away to become slaves - or worse. The church at the edge of town has been desecrated and is being used for dark rituals. The screams that echo in the night are inhuman, but some of our townsfolk may yet survive. Follow the path that lies between my tavern and the blacksmith shop to find the church and save who you can. \n \nPerhaps I can tell you more if we speak again. Good luck.|",
 	    1, 5, TSFX_TAVERN0 }
 };
-const DWORD gdwAllTextEntries = 259; /* unused */
+/** unused */
+const DWORD gdwAllTextEntries = 259;
diff --git a/Source/themes.cpp b/Source/themes.cpp
index 4c9a8ddd..4ebbf3b5 100644
--- a/Source/themes.cpp
+++ b/Source/themes.cpp
@@ -1,3 +1,8 @@
+/**
+ * @file themes.cpp
+ *
+ * Implementation of the theme room placing algorithms.
+ */
 #include "all.h"
 
 int numthemes;
@@ -451,7 +456,9 @@ void InitThemes()
 	}
 }
 
-// HoldThemeRooms marks theme rooms as populated.
+/**
+ * @brief HoldThemeRooms marks theme rooms as populated.
+ */
 void HoldThemeRooms()
 {
 	int i, x, y;
@@ -475,11 +482,12 @@ void HoldThemeRooms()
 	}
 }
 
-// PlaceThemeMonsts places theme monsters with the specified frequency.
-//
-// Parameters:
-//    - t: theme number (index into themes array).
-//    - f: frequency (1/f likelihood of adding monster).
+/**
+ * PlaceThemeMonsts places theme monsters with the specified frequency.
+ *
+ * @param t theme number (index into themes array).
+ * @param f frequency (1/f likelihood of adding monster).
+ */
 void PlaceThemeMonsts(int t, int f)
 {
 	int xp, yp;
@@ -505,10 +513,11 @@ void PlaceThemeMonsts(int t, int f)
 	}
 }
 
-// Theme_Barrel initializes the barrel theme.
-//
-// Parameters:
-//    - t: theme number (index into themes array).
+/**
+ * Theme_Barrel initializes the barrel theme.
+ *
+ * @param t theme number (index into themes array).
+ */
 void Theme_Barrel(int t)
 {
 	int xp, yp, r;
@@ -532,10 +541,11 @@ void Theme_Barrel(int t)
 	PlaceThemeMonsts(t, monstrnd[leveltype - 1]);
 }
 
-// Theme_Shrine initializes the shrine theme.
-//
-// Parameters:
-//    - t: theme number (index into themes array).
+/**
+ * Theme_Shrine initializes the shrine theme.
+ *
+ * @param t theme number (index into themes array).
+ */
 void Theme_Shrine(int t)
 {
 	char monstrnd[4] = { 6, 6, 3, 9 };
@@ -553,10 +563,11 @@ void Theme_Shrine(int t)
 	PlaceThemeMonsts(t, monstrnd[leveltype - 1]);
 }
 
-// Theme_MonstPit initializes the monster pit theme.
-//
-// Parameters:
-//    - t: theme number (index into themes array).
+/**
+ * Theme_MonstPit initializes the monster pit theme.
+ *
+ * @param t theme number (index into themes array).
+ */
 void Theme_MonstPit(int t)
 {
 	int r;
@@ -589,10 +600,11 @@ void Theme_MonstPit(int t)
 	PlaceThemeMonsts(t, monstrnd[leveltype - 1]);
 }
 
-// Theme_SkelRoom initializes the skeleton room theme.
-//
-// Parameters:
-//    - t: theme number (index into themes array).
+/**
+ * Theme_SkelRoom initializes the skeleton room theme.
+ *
+ * @param t theme number (index into themes array).
+ */
 void Theme_SkelRoom(int t)
 {
 	int xp, yp, i;
@@ -658,10 +670,11 @@ void Theme_SkelRoom(int t)
 	}
 }
 
-// Theme_Treasure initializes the treasure theme.
-//
-// Parameters:
-//    - t: theme number (index into themes array).
+/**
+ * Theme_Treasure initializes the treasure theme.
+ *
+ * @param t theme number (index into themes array).
+ */
 void Theme_Treasure(int t)
 {
 	int xp, yp;
@@ -695,10 +708,11 @@ void Theme_Treasure(int t)
 	PlaceThemeMonsts(t, monstrnd[leveltype - 1]);
 }
 
-// Theme_Library initializes the library theme.
-//
-// Parameters:
-//    - t: theme number (index into themes array).
+/**
+ * Theme_Library initializes the library theme.
+ *
+ * @param t theme number (index into themes array).
+ */
 void Theme_Library(int t)
 {
 	int xp, yp, oi;
@@ -740,10 +754,11 @@ void Theme_Library(int t)
 	}
 }
 
-// Theme_Torture initializes the torture theme.
-//
-// Parameters:
-//    - t: theme number (index into themes array).
+/**
+ * Theme_Torture initializes the torture theme.
+ *
+ * @param t theme number (index into themes array).
+ */
 void Theme_Torture(int t)
 {
 	int xp, yp;
@@ -764,10 +779,10 @@ void Theme_Torture(int t)
 	PlaceThemeMonsts(t, monstrnd[leveltype - 1]);
 }
 
-// Theme_BloodFountain initializes the blood fountain theme.
-//
-// Parameters:
-//    - t: theme number (index into themes array).
+/**
+ * Theme_BloodFountain initializes the blood fountain theme.
+ * @param t Theme number (index into themes array).
+ */
 void Theme_BloodFountain(int t)
 {
 	char monstrnd[4] = { 6, 8, 3, 9 };
@@ -777,10 +792,11 @@ void Theme_BloodFountain(int t)
 	PlaceThemeMonsts(t, monstrnd[leveltype - 1]);
 }
 
-// Theme_Decap initializes the decapitated theme.
-//
-// Parameters:
-//    - t: theme number (index into themes array).
+/**
+ * Theme_Decap initializes the decapitated theme.
+ *
+ * @param t theme number (index into themes array).
+ */
 void Theme_Decap(int t)
 {
 	int xp, yp;
@@ -801,10 +817,11 @@ void Theme_Decap(int t)
 	PlaceThemeMonsts(t, monstrnd[leveltype - 1]);
 }
 
-// Theme_PurifyingFountain initializes the purifying fountain theme.
-//
-// Parameters:
-//    - t: theme number (index into themes array).
+/**
+ * Theme_PurifyingFountain initializes the purifying fountain theme.
+ *
+ * @param t theme number (index into themes array).
+ */
 void Theme_PurifyingFountain(int t)
 {
 	char monstrnd[4] = { 6, 7, 3, 9 };
@@ -814,10 +831,11 @@ void Theme_PurifyingFountain(int t)
 	PlaceThemeMonsts(t, monstrnd[leveltype - 1]);
 }
 
-// Theme_ArmorStand initializes the armor stand theme.
-//
-// Parameters:
-//    - t: theme number (index into themes array).
+/**
+ * Theme_ArmorStand initializes the armor stand theme.
+ *
+ * @param t theme number (index into themes array).
+ */
 void Theme_ArmorStand(int t)
 {
 	int xp, yp;
@@ -843,10 +861,11 @@ void Theme_ArmorStand(int t)
 	armorFlag = FALSE;
 }
 
-// Theme_GoatShrine initializes the goat shrine theme.
-//
-// Parameters:
-//    - t: theme number (index into themes array).
+/**
+ * Theme_GoatShrine initializes the goat shrine theme.
+ *
+ * @param t theme number (index into themes array).
+ */
 void Theme_GoatShrine(int t)
 {
 	int xx, yy;
@@ -862,10 +881,11 @@ void Theme_GoatShrine(int t)
 	}
 }
 
-// Theme_Cauldron initializes the cauldron theme.
-//
-// Parameters:
-//    - t: theme number (index into themes array).
+/**
+ * Theme_Cauldron initializes the cauldron theme.
+ *
+ * @param t theme number (index into themes array).
+ */
 void Theme_Cauldron(int t)
 {
 	char monstrnd[4] = { 6, 7, 3, 9 };
@@ -875,10 +895,11 @@ void Theme_Cauldron(int t)
 	PlaceThemeMonsts(t, monstrnd[leveltype - 1]);
 }
 
-// Theme_MurkyFountain initializes the murky fountain theme.
-//
-// Parameters:
-//    - t: theme number (index into themes array).
+/**
+ * Theme_MurkyFountain initializes the murky fountain theme.
+ *
+ * @param t theme number (index into themes array).
+ */
 void Theme_MurkyFountain(int t)
 {
 	char monstrnd[4] = { 6, 7, 3, 9 };
@@ -888,10 +909,11 @@ void Theme_MurkyFountain(int t)
 	PlaceThemeMonsts(t, monstrnd[leveltype - 1]);
 }
 
-// Theme_TearFountain initializes the tear fountain theme.
-//
-// Parameters:
-//    - t: theme number (index into themes array).
+/**
+ * Theme_TearFountain initializes the tear fountain theme.
+ *
+ * @param t theme number (index into themes array).
+ */
 void Theme_TearFountain(int t)
 {
 	char monstrnd[4] = { 6, 7, 3, 9 };
@@ -901,10 +923,11 @@ void Theme_TearFountain(int t)
 	PlaceThemeMonsts(t, monstrnd[leveltype - 1]);
 }
 
-// Theme_BrnCross initializes the burning cross theme.
-//
-// Parameters:
-//    - t: theme number (index into themes array).
+/**
+ * Theme_BrnCross initializes the burning cross theme.
+ *
+ * @param t theme number (index into themes array).
+ */
 void Theme_BrnCross(int t)
 {
 	int xp, yp;
@@ -926,10 +949,11 @@ void Theme_BrnCross(int t)
 	bCrossFlag = TRUE;
 }
 
-// Theme_WeaponRack initializes the weapon rack theme.
-//
-// Parameters:
-//    - t: theme number (index into themes array).
+/**
+ * Theme_WeaponRack initializes the weapon rack theme.
+ *
+ * @param t theme number (index into themes array).
+ */
 void Theme_WeaponRack(int t)
 {
 	int xp, yp;
@@ -955,7 +979,9 @@ void Theme_WeaponRack(int t)
 	weaponFlag = FALSE;
 }
 
-// UpdateL4Trans sets each value of the transparency map to 1.
+/**
+ * UpdateL4Trans sets each value of the transparency map to 1.
+ */
 void UpdateL4Trans()
 {
 	int i, j;
@@ -969,7 +995,9 @@ void UpdateL4Trans()
 	}
 }
 
-// CreateThemeRooms adds thematic elements to rooms.
+/**
+ * CreateThemeRooms adds thematic elements to rooms.
+ */
 void CreateThemeRooms()
 {
 	int i;
diff --git a/Source/themes.h b/Source/themes.h
index 5ee91827..35c4cb08 100644
--- a/Source/themes.h
+++ b/Source/themes.h
@@ -1,4 +1,8 @@
-//HEADER_GOES_HERE
+/**
+ * @file themes.h
+ *
+ * Interface of the theme room placing algorithms.
+ */
 #ifndef __THEMES_H__
 #define __THEMES_H__
 
diff --git a/Source/towners.cpp b/Source/towners.cpp
index 09782e23..103271ef 100644
--- a/Source/towners.cpp
+++ b/Source/towners.cpp
@@ -4,7 +4,8 @@ BOOL storeflag;
 int sgnCowMsg;
 int numtowners;
 DWORD sgdwCowClicks;
-BOOL bannerflag; // unused 0x6AAC28
+/** unused 0x6AAC28 */
+BOOL bannerflag;
 BOOL boyloadflag;
 BYTE *pCowCels;
 TownerStruct towner[16];
diff --git a/defs.h b/defs.h
index 20c09ac7..505eb4bf 100644
--- a/defs.h
+++ b/defs.h
@@ -1,4 +1,8 @@
-// some global definitions, found in debug release
+/**
+ * @file defs.h
+ *
+ * Global definitions and Macros.
+ */
 
 #define GAME_NAME				"DIABLO"
 
diff --git a/doxygen.config b/doxygen.config
new file mode 100644
index 00000000..47dd195f
--- /dev/null
+++ b/doxygen.config
@@ -0,0 +1,34 @@
+PROJECT_NAME           = "Devilution"
+PROJECT_BRIEF          = "Diablo devolved - magic behind the 1996 computer game"
+OUTPUT_DIRECTORY       = docs
+INPUT                  = ./ ./Source
+INPUT_ENCODING         = UTF-8
+FILE_PATTERNS          = *.c \
+                         *.cpp \
+                         *.h \
+                         *.inc
+GENERATE_LATEX         = NO
+
+# Call graphces alows logical navigation of the docs
+CALL_GRAPH             = YES
+CALLER_GRAPH           = YES
+
+# all.h includes everything and everything inclues it so the graph is usless past depth 1
+MAX_DOT_GRAPH_DEPTH    = 1
+
+SOURCE_BROWSER         = YES
+EXTRACT_STATIC         = YES
+JAVADOC_AUTOBRIEF      = YES
+OPTIMIZE_OUTPUT_FOR_C  = YES
+
+HTML_COLORSTYLE_HUE    = 0
+HTML_COLORSTYLE_SAT    = 125
+HTML_COLORSTYLE_GAMMA  = 200
+HTML_DYNAMIC_SECTIONS  = YES
+
+DOT_IMAGE_FORMAT       = svg
+INTERACTIVE_SVG        = YES
+
+# Not all files are documented yet
+EXTRACT_ALL            = YES
+