Add documentation comments for Heretic and Hexen command line arguments.

Subversion-branch: /branches/v2-branch
Subversion-revision: 2611

4 files changed, 275 insertions, 120 deletions

diff --git a/src/heretic/d_main.c b/src/heretic/d_main.c
index f37adcec..8ca49ba6 100644
--- a/src/heretic/d_main.c
+++ b/src/heretic/d_main.c
@@ -418,8 +418,16 @@ void D_CheckRecordFrom(void)
     int p;
     char *filename;
 
-    p = M_CheckParm("-recordfrom");
-    if (!p || p > myargc - 2)
+    //!
+    // @vanilla
+    // @category demo
+    // @arg <savenum> <demofile>
+    //
+    // Record a demo, loading from the given filename. Equivalent
+    // to -loadgame <savenum> -record <demofile>.
+
+    p = M_CheckParmWithArgs("-recordfrom", 2);
+    if (!p)
         return;
 
     filename = SV_Filename(myargv[p + 1][0] - '0');
@@ -799,11 +807,39 @@ void D_DoomMain(void)
 
     I_AtExit(D_Endoom, false);
 
-    nomonsters = M_CheckParm("-nomonsters");
-    respawnparm = M_CheckParm("-respawn");
-    ravpic = M_CheckParm("-ravpic");
-    noartiskip = M_CheckParm("-noartiskip");
-    debugmode = M_CheckParm("-debug");
+    //!
+    // @vanilla
+    //
+    // Disable monsters.
+    //
+
+    nomonsters = M_ParmExists("-nomonsters");
+
+    //!
+    // @vanilla
+    //
+    // Monsters respawn after being killed.
+    //
+
+    respawnparm = M_ParmExists("-respawn");
+
+    //!
+    // @vanilla
+    //
+    // Take screenshots when F1 is pressed.
+    //
+
+    ravpic = M_ParmExists("-ravpic");
+
+    //!
+    // @vanilla
+    //
+    // Allow artifacts to be used when the run key is held down.
+    //
+
+    noartiskip = M_ParmExists("-noartiskip");
+
+    debugmode = M_ParmExists("-debug");
     startskill = sk_medium;
     startepisode = 1;
     startmap = 1;
@@ -812,27 +848,57 @@ void D_DoomMain(void)
 //
 // get skill / episode / map from parms
 //
-    if (M_CheckParm("-deathmatch"))
+
+    //!
+    // @vanilla
+    // @category net
+    //
+    // Start a deathmatch game.
+    //
+
+    if (M_ParmExists("-deathmatch"))
     {
         deathmatch = true;
     }
 
-    p = M_CheckParm("-skill");
-    if (p && p < myargc - 1)
+    //!
+    // @arg <skill>
+    // @vanilla
+    //
+    // Set the game skill, 1-5 (1: easiest, 5: hardest).  A skill of
+    // 0 disables all monsters.
+    //
+
+    p = M_CheckParmWithArgs("-skill", 1);
+    if (p)
     {
         startskill = myargv[p + 1][0] - '1';
         autostart = true;
     }
 
-    p = M_CheckParm("-episode");
-    if (p && p < myargc - 1)
+    //!
+    // @arg <n>
+    // @vanilla
+    //
+    // Start playing on episode n (1-4)
+    //
+
+    p = M_CheckParmWithArgs("-episode", 1);
+    if (p)
     {
         startepisode = myargv[p + 1][0] - '0';
         startmap = 1;
         autostart = true;
     }
 
-    p = M_CheckParm("-warp");
+    //!
+    // @arg <x> <y>
+    // @vanilla
+    //
+    // Start a game immediately, warping to level ExMy.
+    //
+
+    p = M_CheckParmWithArgs("-warp", 2);
     if (p && p < myargc - 2)
     {
         startepisode = myargv[p + 1][0] - '0';
@@ -904,12 +970,30 @@ void D_DoomMain(void)
     D_AddFile(iwadfile);
     W_ParseCommandLine();
 
-    p = M_CheckParm("-playdemo");
+    //!
+    // @arg <demo>
+    // @category demo
+    // @vanilla
+    //
+    // Play back the demo named demo.lmp.
+    //
+
+    p = M_CheckParmWithArgs("-playdemo", 1);
     if (!p)
     {
-        p = M_CheckParm("-timedemo");
+        //!
+        // @arg <demo>
+        // @category demo
+        // @vanilla
+        //
+        // Play back the demo named demo.lmp, determining the framerate
+        // of the screen.
+        //
+
+        p = M_CheckParmWithArgs("-timedemo", 1);
     }
-    if (p && p < myargc - 1)
+
+    if (p)
     {
         DEH_snprintf(file, sizeof(file), "%s.lmp", myargv[p + 1]);
         D_AddFile(file);
@@ -1019,29 +1103,44 @@ void D_DoomMain(void)
 
     D_CheckRecordFrom();
 
-    p = M_CheckParm("-record");
-    if (p && p < myargc - 1)
+    //!
+    // @arg <x>
+    // @category demo
+    // @vanilla
+    //
+    // Record a demo named x.lmp.
+    //
+
+    p = M_CheckParmWithArgs("-record", 1);
+    if (p)
     {
         G_RecordDemo(startskill, 1, startepisode, startmap, myargv[p + 1]);
         D_DoomLoop();           // Never returns
     }
 
-    p = M_CheckParm("-playdemo");
-    if (p && p < myargc - 1)
+    p = M_CheckParmWithArgs("-playdemo", 1);
+    if (p)
     {
         singledemo = true;      // Quit after one demo
         G_DeferedPlayDemo(myargv[p + 1]);
         D_DoomLoop();           // Never returns
     }
 
-    p = M_CheckParm("-timedemo");
-    if (p && p < myargc - 1)
+    p = M_CheckParmWithArgs("-timedemo", 1);
+    if (p)
     {
         G_TimeDemo(myargv[p + 1]);
         D_DoomLoop();           // Never returns
     }
 
-    p = M_CheckParm("-loadgame");
+    //!
+    // @arg <s>
+    // @vanilla
+    //
+    // Load the game in savegame slot s.
+    //
+
+    p = M_CheckParmWithArgs("-loadgame", 1);
     if (p && p < myargc - 1)
     {
         char *filename;
diff --git a/src/heretic/p_setup.c b/src/heretic/p_setup.c
index a3bd2912..7eb7f3c2 100644
--- a/src/heretic/p_setup.c
+++ b/src/heretic/p_setup.c
@@ -620,8 +620,17 @@ void P_SetupLevel(int episode, int map, int playermask, skill_t skill)
                 P_RemoveMobj(mobj);
             }
         }
-        parm = M_CheckParm("-timer");
-        if (parm && parm < myargc - 1)
+
+        //!
+        // @arg <n>
+        // @category net
+        // @vanilla
+        //
+        // For multiplayer games: exit each level after n minutes.
+        //
+
+        parm = M_CheckParmWithArgs("-timer", 1);
+        if (parm)
         {
             TimerGame = atoi(myargv[parm + 1]) * 35 * 60;
         }
diff --git a/src/hexen/h2_main.c b/src/hexen/h2_main.c
index 7b7a8168..33d345e8 100644
--- a/src/hexen/h2_main.c
+++ b/src/hexen/h2_main.c
@@ -63,16 +63,6 @@
 #define CT_KEY_PLAYER8      'p'     // Purple
 #define CT_KEY_ALL          't'
 
-// TYPES -------------------------------------------------------------------
-
-typedef struct
-{
-    char *name;
-    void (*func) (char **args, int tag);
-    int requiredArgs;
-    int tag;
-} execOpt_t;
-
 // EXTERNAL FUNCTION PROTOTYPES --------------------------------------------
 
 void R_ExecuteSetViewSize(void);
@@ -99,10 +89,6 @@ static void PageDrawer(void);
 static void HandleArgs(void);
 static void CheckRecordFrom(void);
 static void DrawAndBlit(void);
-static void ExecOptionSCRIPTS(char **args, int tag);
-static void ExecOptionSKILL(char **args, int tag);
-static void ExecOptionPLAYDEMO(char **args, int tag);
-static void ExecOptionTestControls(char **args, int tag);
 static void CreateSavePath(void);
 static void WarpCheck(void);
 
@@ -142,15 +128,6 @@ static int demosequence;
 static int pagetic;
 static char *pagename;
 
-static execOpt_t ExecOptions[] = {
-    {"-scripts", ExecOptionSCRIPTS, 1, 0},
-    {"-skill", ExecOptionSKILL, 1, 0},
-    {"-playdemo", ExecOptionPLAYDEMO, 1, 0},
-    {"-timedemo", ExecOptionPLAYDEMO, 1, 0},
-    {"-testcontrols", ExecOptionTestControls, 0, 0},
-    {NULL, NULL, 0, 0}          // Terminator
-};
-
 // CODE --------------------------------------------------------------------
 
 void D_BindVariables(void)
@@ -397,23 +374,30 @@ void D_DoomMain(void)
         H2_GameLoop();          // Never returns
     }
 
-    p = M_CheckParm("-playdemo");
-    if (p && p < myargc - 1)
+    p = M_CheckParmWithArgs("-playdemo", 1);
+    if (p)
     {
         singledemo = true;      // Quit after one demo
         G_DeferedPlayDemo(myargv[p + 1]);
         H2_GameLoop();          // Never returns
     }
 
-    p = M_CheckParm("-timedemo");
-    if (p && p < myargc - 1)
+    p = M_CheckParmWithArgs("-timedemo", 1);
+    if (p)
     {
         G_TimeDemo(myargv[p + 1]);
         H2_GameLoop();          // Never returns
     }
 
-    p = M_CheckParm("-loadgame");
-    if (p && p < myargc - 1)
+    //!
+    // @arg <s>
+    // @vanilla
+    //
+    // Load the game in savegame slot s.
+    //
+
+    p = M_CheckParmWithArgs("-loadgame", 1);
+    if (p)
     {
         G_LoadGame(atoi(myargv[p + 1]));
     }
@@ -444,29 +428,141 @@ void D_DoomMain(void)
 static void HandleArgs(void)
 {
     int p;
-    execOpt_t *opt;
+
+    //!
+    // @vanilla
+    //
+    // Disable monsters.
+    //
 
     nomonsters = M_ParmExists("-nomonsters");
+
+    //!
+    // @vanilla
+    //
+    // Monsters respawn after being killed.
+    //
+
     respawnparm = M_ParmExists("-respawn");
+
+    //!
+    // @vanilla
+    // @category net
+    //
+    // In deathmatch mode, change a player's class each time the
+    // player respawns.
+    //
+
     randomclass = M_ParmExists("-randclass");
+
+    //!
+    // @vanilla
+    //
+    // Take screenshots when F1 is pressed.
+    //
+
     ravpic = M_ParmExists("-ravpic");
+
+    //!
+    // @vanilla
+    //
+    // Don't allow artifacts to be used when the run key is held down.
+    //
+
     artiskip = M_ParmExists("-artiskip");
+
     debugmode = M_ParmExists("-debug");
+
+    //!
+    // @vanilla
+    // @category net
+    //
+    // Start a deathmatch game.
+    //
+
     deathmatch = M_ParmExists("-deathmatch");
 
+    // currently broken or unused:
     cmdfrag = M_ParmExists("-cmdfrag");
 
     // Check WAD file command line options
     W_ParseCommandLine();
 
-    // Process command line options
-    for (opt = ExecOptions; opt->name != NULL; opt++)
+    //!
+    // @vanilla
+    // @arg <path>
+    //
+    // Development option to specify path to level scripts.
+    //
+
+    p = M_CheckParmWithArgs("-scripts", 1);
+
+    if (p)
     {
-        p = M_CheckParm(opt->name);
-        if (p && p < myargc - opt->requiredArgs)
+        sc_FileScripts = true;
+        sc_ScriptsDir = myargv[p+1];
+    }
+
+    //!
+    // @arg <skill>
+    // @vanilla
+    //
+    // Set the game skill, 1-5 (1: easiest, 5: hardest).  A skill of
+    // 0 disables all monsters.
+    //
+
+    p = M_CheckParmWithArgs("-skill", 1);
+
+    if (p)
+    {
+        startskill = myargv[p+1][0] - '1';
+        autostart = true;
+    }
+
+    //!
+    // @arg <demo>
+    // @category demo
+    // @vanilla
+    //
+    // Play back the demo named demo.lmp.
+    //
+
+    p = M_CheckParmWithArgs("-playdemo", 1);
+
+    if (!p)
+    {
+        //!
+        // @arg <demo>
+        // @category demo
+        // @vanilla
+        //
+        // Play back the demo named demo.lmp, determining the framerate
+        // of the screen.
+        //
+
+        p = M_CheckParmWithArgs("-timedemo", 1);
+    }
+
+    if (p)
+    {
+        char file[256];
+
+        strncpy(file, myargv[p+1], sizeof(file));
+        file[sizeof(file) - 6] = '\0';
+
+        if (strcasecmp(file + strlen(file) - 4, ".lmp") != 0)
         {
-            opt->func(&myargv[p], opt->tag);
+            strcat(file, ".lmp");
         }
+
+        W_AddFile(file);
+        ST_Message("Playing demo %s.\n", file);
+    }
+
+    if (M_ParmExists("-testcontrols"))
+    {
+        autostart = true;
+        testcontrols = true;
     }
 }
 
@@ -510,64 +606,6 @@ static void WarpCheck(void)
 
 //==========================================================================
 //
-// ExecOptionSKILL
-//
-//==========================================================================
-
-static void ExecOptionSKILL(char **args, int tag)
-{
-    startskill = args[1][0] - '1';
-    autostart = true;
-}
-
-//==========================================================================
-//
-// ExecOptionPLAYDEMO
-//
-//==========================================================================
-
-static void ExecOptionPLAYDEMO(char **args, int tag)
-{
-    char file[256];
-
-    strcpy(file, args[1]);
-
-    if (strcasecmp(file + strlen(file) - 4, ".lmp") != 0)
-    {
-        strcat(file, ".lmp");
-    }
-
-    W_AddFile(file);
-    ST_Message("Playing demo %s.\n", file);
-}
-
-//==========================================================================
-//
-// ExecOptionTestControls
-//
-//==========================================================================
-
-static void ExecOptionTestControls(char **args, int tag)
-{
-    autostart = true;
-    testcontrols = true;
-}
-
-//==========================================================================
-//
-// ExecOptionSCRIPTS
-//
-//==========================================================================
-
-static void ExecOptionSCRIPTS(char **args, int tag)
-{
-    sc_FileScripts = true;
-    sc_ScriptsDir = args[1];
-}
-
-
-//==========================================================================
-//
 // H2_GameLoop
 //
 //==========================================================================
diff --git a/src/hexen/p_setup.c b/src/hexen/p_setup.c
index 1d7c943a..57c4ab8c 100644
--- a/src/hexen/p_setup.c
+++ b/src/hexen/p_setup.c
@@ -747,8 +747,17 @@ void P_SetupLevel(int episode, int map, int playermask, skill_t skill)
                 P_RemoveMobj(mobj);
             }
         }
-        parm = M_CheckParm("-timer");
-        if (parm && parm < myargc - 1)
+
+        //!
+        // @arg <n>
+        // @category net
+        // @vanilla
+        //
+        // For multiplayer games: exit each level after n minutes.
+        //
+
+        parm = M_CheckParmWithArgs("-timer", 1);
+        if (parm)
         {
             TimerGame = atoi(myargv[parm + 1]) * 35 * 60;
         }