Javadoc-style self-documenting system for command line options.

Subversion-branch: /trunk/chocolate-doom
Subversion-revision: 806

12 files changed, 435 insertions, 30 deletions

diff --git a/src/d_iwad.c b/src/d_iwad.c
index 612f2434..7d21c92e 100644
--- a/src/d_iwad.c
+++ b/src/d_iwad.c
@@ -465,6 +465,12 @@ char *D_FindIWAD(void)
 
     // Check for the -iwad parameter
 
+    //!
+    // Specify an IWAD file to use.
+    //
+    // @arg <file>
+    //
+
     iwadparm = M_CheckParm("-iwad");
 
     if (iwadparm)
diff --git a/src/d_main.c b/src/d_main.c
index af892d30..881e4dd9 100644
--- a/src/d_main.c
+++ b/src/d_main.c
@@ -833,6 +833,14 @@ static void InitGameVersion(void)
     int p;
     int i;
 
+    //! 
+    // @arg <version>
+    // @category compat
+    //
+    // Emulate a specific version of Doom.  Valid values are "1.9",
+    // "ultimate" and "final".
+    //
+
     p = M_CheckParm("-gameversion");
 
     if (p > 0)
@@ -929,6 +937,9 @@ void D_DoomMain (void)
 
     FindResponseFile ();
 
+    // Undocumented "search for IWADs" parameter used by the setup
+    // tool.
+
     if (M_CheckParm("-findiwads") > 0)
     {
         D_FindInstalledIWADs();
@@ -941,6 +952,13 @@ void D_DoomMain (void)
     printf (DEH_String("Z_Init: Init zone memory allocation daemon. \n"));
     Z_Init ();
 
+    //!
+    // @category net
+    //
+    // Start a dedicated server, routing packets but not participating
+    // in the game itself.
+    //
+
     if (M_CheckParm("-dedicated") > 0)
     {
         printf("Dedicated server mode.\n");
@@ -949,7 +967,13 @@ void D_DoomMain (void)
         // Never returns
     }
 
-    // Query network servers?
+    //!
+    // @arg <address>
+    // @category net
+    //
+    // Query the status of the server running on the given IP
+    // address.
+    //
 
     p = M_CheckParm("-query");
 
@@ -958,6 +982,12 @@ void D_DoomMain (void)
         NET_QueryAddress(myargv[p+1]);
     }
 
+    //!
+    // @category net
+    //
+    // Search the local LAN for running servers.
+    //
+
     if (M_CheckParm("-search"))
         NET_LANQuery();
             
@@ -978,15 +1008,50 @@ void D_DoomMain (void)
 	
     setbuf (stdout, NULL);
     modifiedgame = false;
+
+    //!
+    // Disable monsters.
+    //
 	
     nomonsters = M_CheckParm ("-nomonsters");
+
+    //!
+    // Monsters respawn after being killed.
+    //
+
     respawnparm = M_CheckParm ("-respawn");
+
+    //!
+    // Monsters move faster.
+    //
+
     fastparm = M_CheckParm ("-fast");
+
+    //! 
+    // Developer mode.  F1 saves a screenshot in the current working
+    // directory.
+    //
+
     devparm = M_CheckParm ("-devparm");
+
+    //!
+    // @category net
+    //
+    // Start a deathmatch game.
+    //
+
+    if (M_CheckParm ("-deathmatch"))
+	deathmatch = 1;
+
+    //!
+    // @category net
+    //
+    // Start a deathmatch 2.0 game.  Weapons do not stay in place and
+    // all items respawn after 30 seconds.
+    //
+
     if (M_CheckParm ("-altdeath"))
 	deathmatch = 2;
-    else if (M_CheckParm ("-deathmatch"))
-	deathmatch = 1;
 
     if (devparm)
 	printf(DEH_String(D_DEVSTR));
@@ -995,7 +1060,13 @@ void D_DoomMain (void)
 
     M_SetConfigDir();
     
-    // turbo option
+    //!
+    // @arg <x>
+    //
+    // Turbo mode.  The player's speed is multiplied by x%.  If unspecified,
+    // x defaults to 200.  Values are rounded up to 10 and down to 400.
+    //
+
     if ( (p=M_CheckParm ("-turbo")) )
     {
 	int     scale = 200;
@@ -1030,6 +1101,14 @@ void D_DoomMain (void)
     // Merged PWADs are loaded first, because they are supposed to be 
     // modified IWADs.
 
+    //!
+    // @arg <files>
+    // @category mod
+    //
+    // Simulates the behavior of deutex's -merge option, merging a PWAD
+    // into the main IWAD.  Multiple files may be specified.
+    //
+
     p = M_CheckParm("-merge");
 
     if (p > 0)
@@ -1045,6 +1124,13 @@ void D_DoomMain (void)
 
     // NWT's -merge option:
 
+    //!
+    // @arg <files>
+    // @category mod
+    //
+    // Simulates the behavior of NWT's -merge option.  Multiple files
+    // may be specified.
+
     p = M_CheckParm("-nwtmerge");
 
     if (p > 0)
@@ -1058,6 +1144,14 @@ void D_DoomMain (void)
     
     // Add flats
 
+    //!
+    // @arg <files>
+    // @category mod
+    //
+    // Simulates the behavior of NWT's -af option, merging flats into
+    // the main IWAD directory.  Multiple files may be specified.
+    //
+
     p = M_CheckParm("-af");
 
     if (p > 0)
@@ -1069,7 +1163,13 @@ void D_DoomMain (void)
         }
     }
 
-    // Add sprites
+    //!
+    // @arg <files>
+    // @category mod
+    //
+    // Simulates the behavior of NWT's -as option, merging sprites
+    // into the main IWAD directory.  Multiple files may be specified.
+    //
 
     p = M_CheckParm("-as");
 
@@ -1082,7 +1182,12 @@ void D_DoomMain (void)
         }
     }
 
-    // Add sprites AND flats
+    //!
+    // @arg <files>
+    // @category mod
+    //
+    // Equivalent to "-af <files> -as <files>".
+    //
 
     p = M_CheckParm("-aa");
 
@@ -1097,7 +1202,11 @@ void D_DoomMain (void)
 
 #endif
 
-    // Load normal PWADs
+    //!
+    // @arg <files>
+    //
+    // Load the specified PWAD files.
+    //
 
     p = M_CheckParm ("-file");
     if (p)
@@ -1145,12 +1254,29 @@ void D_DoomMain (void)
 	}
 	D_AddFile (file);
     }
-	
+
+    //!
+    // @arg <demo>
+    // @category demo
+    //
+    // Play back the demo named demo.lmp.
+    //
+
     p = M_CheckParm ("-playdemo");
 
     if (!p)
+    {
+        //!
+        // @arg <demo>
+        // @category demo
+        //
+        // Play back the demo named demo.lmp, determining the framerate
+        // of the screen.
+        //
 	p = M_CheckParm ("-timedemo");
 
+    }
+
     if (p && p < myargc-1)
     {
         if (!strcasecmp(myargv[p+1] + strlen(myargv[p+1]) - 4, ".lmp"))
@@ -1221,15 +1347,29 @@ void D_DoomMain (void)
     startmap = 1;
     autostart = false;
 
-		
+    //!
+    // @arg <skill>
+    //
+    // Set the game skill, 1-5 (1: easiest, 5: hardest).  A skill of
+    // 0 disables all monsters.
+    //
+
     p = M_CheckParm ("-skill");
+
     if (p && p < myargc-1)
     {
 	startskill = myargv[p+1][0]-'1';
 	autostart = true;
     }
 
+    //!
+    // @arg <n>
+    //
+    // Start playing on episode n (1-4)
+    //
+
     p = M_CheckParm ("-episode");
+
     if (p && p < myargc-1)
     {
 	startepisode = myargv[p+1][0]-'0';
@@ -1239,14 +1379,29 @@ void D_DoomMain (void)
 	
     timelimit = 0;
 
+    //! 
+    // @arg <n>
+    // @category net
+    //
+    // For multiplayer games: exit each level after n minutes.
+    //
+
     p = M_CheckParm ("-timer");
+
     if (p && p < myargc-1 && deathmatch)
     {
 	timelimit = atoi(myargv[p+1]);
 	printf("timer: %i\n", timelimit);
     }
 
+    //!
+    // @category net
+    //
+    // Austin Virtual Gaming: end levels after 20 minutes.
+    //
+
     p = M_CheckParm ("-avg");
+
     if (p && p < myargc-1 && deathmatch)
     {
 	printf(DEH_String("Austin Virtual Gaming: Levels will end "
@@ -1254,7 +1409,15 @@ void D_DoomMain (void)
 	timelimit = 20;
     }
 
+    //!
+    // @arg [<x> <y> | <xy>]
+    //
+    // Start a game immediately, warping to ExMy (Doom 1) or MAPxy
+    // (Doom 2)
+    //
+
     p = M_CheckParm ("-warp");
+
     if (p && p < myargc-1)
     {
         if (gamemode == commercial)
@@ -1275,6 +1438,7 @@ void D_DoomMain (void)
         autostart = true;
     }
 
+    // Undocumented:
     // Invoked by setup to test the controls.
 
     p = M_CheckParm("-testcontrols");
@@ -1291,6 +1455,12 @@ void D_DoomMain (void)
     // We do this here and save the slot number, so that the network code
     // can override it or send the load slot to other players.
 
+    //!
+    // @arg <s>
+    //
+    // Load the game in slot s.
+    //
+
     p = M_CheckParm ("-loadgame");
     
     if (p && p < myargc-1)
@@ -1303,9 +1473,22 @@ void D_DoomMain (void)
         startloadgame = -1;
     }
 
+    //!
+    // @category video
+    //
+    // Disable vertical mouse movement.
+    //
+
     if (M_CheckParm("-novert"))
         novert = true;
-    else if (M_CheckParm("-nonovert"))
+
+    //!
+    // @category video
+    //
+    // Enable vertical mouse movement.
+    //
+
+    if (M_CheckParm("-nonovert"))
         novert = false;
 
     if (W_CheckNumForName("SS_START") >= 0
@@ -1372,7 +1555,13 @@ void D_DoomMain (void)
     if (gamemode == commercial && W_CheckNumForName("map01") < 0)
         storedemo = true;
 
-    // start the apropriate game based on parms
+    //!
+    // @arg <x>
+    // @category demo
+    //
+    // Record a demo named x.lmp.
+    //
+
     p = M_CheckParm ("-record");
 
     if (p && p < myargc-1)
@@ -1380,7 +1569,7 @@ void D_DoomMain (void)
 	G_RecordDemo (myargv[p+1]);
 	autostart = true;
     }
-	
+
     p = M_CheckParm ("-playdemo");
     if (p && p < myargc-1)
     {
diff --git a/src/d_net.c b/src/d_net.c
index c00d5f61..559bd448 100644
--- a/src/d_net.c
+++ b/src/d_net.c
@@ -248,6 +248,12 @@ void D_CheckNetGame (void)
     {
         net_addr_t *addr = NULL;
 
+        //!
+        // @category net
+        //
+        // Start a multiplayer server, listening for connections.
+        //
+
         if (M_CheckParm("-server") > 0)
         {
             NET_SV_Init();
@@ -259,6 +265,13 @@ void D_CheckNetGame (void)
         }
         else
         {
+            //! 
+            // @category net
+            //
+            // Automatically search the local LAN for a multiplayer
+            // server and join it.
+            //
+
             i = M_CheckParm("-autojoin");
 
             if (i > 0)
@@ -270,6 +283,14 @@ void D_CheckNetGame (void)
                     I_Error("No server found on local LAN");
                 }
             }
+
+            //!
+            // @arg <address>
+            // @category net
+            //
+            // Connect to a multiplayer server running on the given 
+            // address.
+            //
             
             i = M_CheckParm("-connect");
 
@@ -292,12 +313,24 @@ void D_CheckNetGame (void)
                 drone = true;
             }
 
+            //!
+            // @category net
+            //
+            // Run as the left screen in three screen mode.
+            //
+
             if (M_CheckParm("-left") > 0)
             {
                 viewangleoffset = ANG90;
                 drone = true;
             }
 
+            //! 
+            // @category net
+            //
+            // Run as the right screen in three screen mode.
+            //
+
             if (M_CheckParm("-right") > 0)
             {
                 viewangleoffset = ANG270;
diff --git a/src/deh_main.c b/src/deh_main.c
index 8f82b5bb..887dd1e4 100644
--- a/src/deh_main.c
+++ b/src/deh_main.c
@@ -339,6 +339,13 @@ void DEH_Init(void)
 
     InitialiseSections();
 
+    //!
+    // @arg <files>
+    // @category mod
+    //
+    // Load the given dehacked patch(es)
+    //
+
     p = M_CheckParm("-deh");
 
     if (p > 0)
diff --git a/src/g_game.c b/src/g_game.c
index 971b7855..8fd96ec4 100644
--- a/src/g_game.c
+++ b/src/g_game.c
@@ -1800,6 +1800,14 @@ void G_RecordDemo (char* name)
     strcpy (demoname, name); 
     strcat (demoname, ".lmp"); 
     maxsize = 0x20000;
+
+    //!
+    // @arg <size>
+    // @category demo
+    //
+    // Specify the demo buffer size (KiB)
+    //
+
     i = M_CheckParm ("-maxdemo");
     if (i && i<myargc-1)
 	maxsize = atoi(myargv[i+1])*1024;
@@ -1814,8 +1822,12 @@ void G_BeginRecording (void)
 { 
     int             i; 
 
-    // Check for the longtics parameter, to record hires angle
-    // turns in demos
+    //!
+    // @category demo
+    //
+    // Record a high resolution "Doom 1.91" demo.
+    //
+
     longtics = M_CheckParm("-longtics") != 0;
 
     // If not recording a longtics demo, record in low res
@@ -1921,8 +1933,17 @@ void G_DoPlayDemo (void)
 // G_TimeDemo 
 //
 void G_TimeDemo (char* name) 
-{ 	 
+{
+    //!
+    // Disable rendering the screen entirely.
+    //
+
     nodrawers = M_CheckParm ("-nodraw"); 
+
+    //!
+    // Disable blitting the screen.
+    //
+
     noblit = M_CheckParm ("-noblit"); 
     timingdemo = true; 
     singletics = true; 
diff --git a/src/i_sound.c b/src/i_sound.c
index fbf5768c..bdb82c53 100644
--- a/src/i_sound.c
+++ b/src/i_sound.c
@@ -453,12 +453,37 @@ I_InitSound()
         channels_playing[i] = sfx_None;
     }
 
-    nomusicparm = M_CheckParm("-nomusic") > 0
-               || M_CheckParm("-nosound") > 0
-               || snd_musicdevice < SNDDEVICE_ADLIB;
-    nosfxparm = M_CheckParm("-nosfx") > 0
-             || M_CheckParm("-nosound") > 0
-             || snd_sfxdevice < SNDDEVICE_SB;
+    //! 
+    // Disable music playback.
+    //
+
+    nomusicparm = M_CheckParm("-nomusic") > 0;
+
+    if (snd_musicdevice < SNDDEVICE_ADLIB)
+    {
+        nomusicparm = true;
+    }
+
+    //!
+    // Disable sound effects.
+    //
+
+    nosfxparm = M_CheckParm("-nosfx") > 0;
+
+    if (snd_sfxdevice < SNDDEVICE_SB)
+    {
+        nosfxparm = true;
+    }
+
+    //!
+    // Disable sound effects and music.
+    //
+
+    if (M_CheckParm("-nosound") > 0)
+    {
+        nosfxparm = true;
+        nomusicparm = true;
+    }
 
     // If music or sound is going to play, we need to at least
     // initialise SDL
diff --git a/src/i_system.c b/src/i_system.c
index 3107465d..1009b23d 100644
--- a/src/i_system.c
+++ b/src/i_system.c
@@ -75,6 +75,12 @@ int  I_GetHeapSize (void)
 {
     int p;
 
+    //!
+    // @arg <mb>
+    //
+    // Specify the heap size, in MiB (default 16).
+    //
+
     p = M_CheckParm("-mb");
     
     if (p > 0)
diff --git a/src/i_video.c b/src/i_video.c
index eaa4bc38..92dc9b28 100644
--- a/src/i_video.c
+++ b/src/i_video.c
@@ -866,13 +866,24 @@ static boolean CheckValidFSMode(void)
 
 static void CheckCommandLine(void)
 {
-    // mouse grabbing
+    //!
+    // @category video 
+    //
+    // Grab the mouse when running in windowed mode.
+    //
 
     if (M_CheckParm("-grabmouse"))
     {
         grabmouse = true;
     }
-    else if (M_CheckParm("-nograbmouse"))
+
+    //!
+    // @category video 
+    //
+    // Don't grab the mouse when running in windowed mode.
+    //
+
+    if (M_CheckParm("-nograbmouse"))
     {
         grabmouse = false;
     }
@@ -880,32 +891,78 @@ static void CheckCommandLine(void)
     // default to fullscreen mode, allow override with command line
     // nofullscreen because we love prboom
 
+    //!
+    // @category video 
+    //
+    // Run in a window.
+    //
+
     if (M_CheckParm("-window") || M_CheckParm("-nofullscreen"))
     {
         fullscreen = FULLSCREEN_OFF;
     }
-    else if (M_CheckParm("-fullscreen"))
+
+    //!
+    // @category video 
+    //
+    // Run in fullscreen mode.
+    //
+
+    if (M_CheckParm("-fullscreen"))
     {
         fullscreen = FULLSCREEN_ON;
     }
 
+    //!
+    // @category video 
+    //
+    // Disable the mouse.
+    //
+
     nomouse = M_CheckParm("-nomouse") > 0;
 
-    // scale-by-2 mode
+    // 2x, 3x, 4x scale mode
  
+    //!
+    // @category video 
+    //
+    // Don't scale up the screen.
+    //
+
     if (M_CheckParm("-1"))
     {
         screenmultiply = 1;
     }
-    else if (M_CheckParm("-2"))
+
+    //!
+    // @category video 
+    //
+    // Double up the screen to 2x its size.
+    //
+
+    if (M_CheckParm("-2"))
     {
         screenmultiply = 2;
     }
-    else if (M_CheckParm("-3"))
+
+    //!
+    // @category video 
+    //
+    // Double up the screen to 3x its size.
+    //
+
+    if (M_CheckParm("-3"))
     {
         screenmultiply = 3;
     }
-    else if (M_CheckParm("-4"))
+
+    //!
+    // @category video 
+    //
+    // Double up the screen to 4x its size.
+    //
+
+    if (M_CheckParm("-4"))
     {
         screenmultiply = 4;
     }
@@ -1062,6 +1119,13 @@ void I_InitGraphics(void)
 
     // Allow -gdi as a shortcut for using the windib driver.
 
+    //!
+    // @category video 
+    // @platform windows
+    //
+    // Use the Windows GDI driver instead of DirectX.
+    //
+
     if (M_CheckParm("-gdi") > 0)
     {
         putenv("SDL_VIDEODRIVER=windib");
diff --git a/src/m_misc.c b/src/m_misc.c
index ff268ef0..5b98960a 100644
--- a/src/m_misc.c
+++ b/src/m_misc.c
@@ -616,6 +616,14 @@ void M_LoadDefaults (void)
     int i;
  
     // check for a custom default file
+
+    //!
+    // @arg <file>
+    //
+    // Load configuration from the specified file, instead of
+    // default.cfg.
+    //
+
     i = M_CheckParm ("-config");
 
     if (i && i<myargc-1)
@@ -631,6 +639,11 @@ void M_LoadDefaults (void)
 
     printf("saving config in %s\n", doom_defaults.filename);
 
+    //!
+    // Load extra configuration from the specified file, instead 
+    // of chocolate-doom.cfg.
+    //
+
     i = M_CheckParm("-extraconfig");
 
     if (i && i<myargc-1)
@@ -681,8 +694,12 @@ void M_SetConfigDir(void)
     else
     {
 #ifdef _WIN32
-        // when given the -cdrom option, save config+savegames in 
-        // c:\doomdata.  This only applies under Windows.
+        //!
+        // @platform windows
+        //
+        // Save configuration data and savegames in c:\doomdata,
+        // allowing play from CD.
+        //
 
         if (M_CheckParm("-cdrom") > 0)
         {
diff --git a/src/net_client.c b/src/net_client.c
index 1bfeb3f9..12e56041 100644
--- a/src/net_client.c
+++ b/src/net_client.c
@@ -390,11 +390,25 @@ void NET_CL_StartGame(void)
     settings.nomonsters = nomonsters;
     settings.timelimit = timelimit;
 
+    //!
+    // @category net
+    //
+    // Use original game sync code.
+    //
+
     if (M_CheckParm("-oldsync") > 0)
 	settings.new_sync = 0;
     else
 	settings.new_sync = 1;
     
+    //!
+    // @category net
+    // @arg <n>
+    //
+    // Send n extra tics in every packet as insurance against dropped
+    // packets.
+    //
+
     i = M_CheckParm("-extratics");
 
     if (i > 0)
@@ -402,6 +416,14 @@ void NET_CL_StartGame(void)
     else
         settings.extratics = 1;
 
+    //!
+    // @category net
+    // @arg <n>
+    //
+    // Reduce the resolution of the game by a factor of n, reducing
+    // the amount of network bandwidth needed.
+    //
+
     i = M_CheckParm("-dup");
 
     if (i > 0)
diff --git a/src/net_sdl.c b/src/net_sdl.c
index 09d1dbb0..255feba4 100644
--- a/src/net_sdl.c
+++ b/src/net_sdl.c
@@ -161,6 +161,14 @@ static boolean NET_SDL_InitClient(void)
 {
     int p;
 
+    //!
+    // @category net
+    // @arg <n>
+    //
+    // Use the specified UDP port for communications, instead of 
+    // the default (2342).
+    //
+
     p = M_CheckParm("-port");
     if (p > 0)
         port = atoi(myargv[p+1]);
diff --git a/src/p_map.c b/src/p_map.c
index 4b5eac96..9f52aa13 100644
--- a/src/p_map.c
+++ b/src/p_map.c
@@ -1379,6 +1379,13 @@ static void SpechitOverrun(line_t *ld)
         // what base address we are going to use.
         // Allow a spechit value to be specified on the command line.
 
+        //!
+        // @category compat
+        // @arg <n>
+        //
+        // Use the specified magic value when emulating spechit overruns.
+        //
+
         p = M_CheckParm("-spechit");
         
         if (p > 0)