From ceefa5bbd95c97d5299f8a81f6ce83a1ae83c55b Mon Sep 17 00:00:00 2001 From: Simon Howard Date: Fri, 16 Mar 2018 21:20:55 -0400 Subject: [PATCH] docgen: Add 'game' and 'obscure' categories. The "general options" section of the manpage(s) has become quite cluttered, and some of the options are obscure things most people don't need to know about. Move the really obscure ones into their own category near the end of the manpage, and factor out the options used when starting a game from the command line into their own section as well. Also add some missing doc comments for Hexen command line options. --- man/docgen | 33 ++++++++++++++------------------- src/doom/d_main.c | 13 +++++++++++-- src/heretic/d_main.c | 8 ++++++++ src/hexen/h2_main.c | 31 +++++++++++++++++++++++++++++++ src/i_sdlmusic.c | 1 + src/i_system.c | 3 +++ src/strife/d_main.c | 12 ++++++++++++ src/w_file.c | 2 ++ 8 files changed, 82 insertions(+), 21 deletions(-) diff --git a/man/docgen b/man/docgen index 0a388a74..cdaac238 100755 --- a/man/docgen +++ b/man/docgen @@ -157,14 +157,16 @@ class Category: return result -categories = { - None: Category("General options"), - "video": Category("Display options"), - "demo": Category("Demo options"), - "net": Category("Networking options"), - "mod": Category("Dehacked and WAD merging"), - "compat": Category("Compatibility"), -} +categories = ( + (None, Category("General options")), + ("game", Category("Game start options")), + ("video", Category("Display options")), + ("net", Category("Networking options")), + ("mod", Category("Dehacked and WAD merging")), + ("demo", Category("Demo options")), + ("compat", Category("Compatibility")), + ("obscure", Category("Obscure and less-used options")), +) wikipages = [] config_files = {} @@ -347,7 +349,8 @@ def add_parameter(param, line, config_file): if match: param.name = match.group(3) - categories[param.category].add_param(param) + category = dict(categories)[param.category] + category.add_param(param) return # Documenting a configuration file variable? @@ -550,19 +553,11 @@ else: process_files(path) # Build a list of things to document - - documentation_targets = [] - if doc_config_file: - documentation_targets.append(config_files[doc_config_file]) + documentation_targets = [config_files[doc_config_file]] else: - documentation_targets.append(categories[None]) - - for c in categories: - if c != None: - documentation_targets.append(categories[c]) + documentation_targets = [c for _, c in categories] # Generate the output - output_function(documentation_targets, substs, template) diff --git a/src/doom/d_main.c b/src/doom/d_main.c index 8c122bcd..629b563d 100644 --- a/src/doom/d_main.c +++ b/src/doom/d_main.c @@ -1286,6 +1286,7 @@ void D_DoomMain (void) } //! + // @category game // @vanilla // // Disable monsters. @@ -1294,6 +1295,7 @@ void D_DoomMain (void) nomonsters = M_CheckParm ("-nomonsters"); //! + // @category game // @vanilla // // Monsters respawn after being killed. @@ -1302,6 +1304,7 @@ void D_DoomMain (void) respawnparm = M_CheckParm ("-respawn"); //! + // @category game // @vanilla // // Monsters move faster. @@ -1309,10 +1312,10 @@ void D_DoomMain (void) fastparm = M_CheckParm ("-fast"); - //! + //! // @vanilla // - // Developer mode. F1 saves a screenshot in the current working + // Developer mode. F1 saves a screenshot in the current working // directory. // @@ -1349,6 +1352,7 @@ void D_DoomMain (void) #ifdef _WIN32 //! + // @category obscure // @platform windows // @vanilla // @@ -1371,6 +1375,7 @@ void D_DoomMain (void) } //! + // @category game // @arg // @vanilla // @@ -1683,6 +1688,7 @@ void D_DoomMain (void) autostart = false; //! + // @category game // @arg // @vanilla // @@ -1699,6 +1705,7 @@ void D_DoomMain (void) } //! + // @category game // @arg // @vanilla // @@ -1746,6 +1753,7 @@ void D_DoomMain (void) } //! + // @category game // @arg [ | ] // @vanilla // @@ -1793,6 +1801,7 @@ void D_DoomMain (void) // can override it or send the load slot to other players. //! + // @category game // @arg // @vanilla // diff --git a/src/heretic/d_main.c b/src/heretic/d_main.c index 145ea4aa..2fdcb105 100644 --- a/src/heretic/d_main.c +++ b/src/heretic/d_main.c @@ -737,6 +737,7 @@ void D_DoomMain(void) I_AtExit(D_Endoom, false); //! + // @category game // @vanilla // // Disable monsters. @@ -745,6 +746,7 @@ void D_DoomMain(void) nomonsters = M_ParmExists("-nomonsters"); //! + // @category game // @vanilla // // Monsters respawn after being killed. @@ -761,6 +763,7 @@ void D_DoomMain(void) ravpic = M_ParmExists("-ravpic"); //! + // @category obscure // @vanilla // // Allow artifacts to be used when the run key is held down. @@ -791,6 +794,7 @@ void D_DoomMain(void) } //! + // @category game // @arg // @vanilla // @@ -806,6 +810,7 @@ void D_DoomMain(void) } //! + // @category game // @arg // @vanilla // @@ -821,6 +826,7 @@ void D_DoomMain(void) } //! + // @category game // @arg // @vanilla // @@ -848,6 +854,7 @@ void D_DoomMain(void) #ifdef _WIN32 //! + // @category obscure // @platform windows // @vanilla // @@ -1102,6 +1109,7 @@ void D_DoomMain(void) } //! + // @category game // @arg // @vanilla // diff --git a/src/hexen/h2_main.c b/src/hexen/h2_main.c index c0897e03..2a9f232c 100644 --- a/src/hexen/h2_main.c +++ b/src/hexen/h2_main.c @@ -371,6 +371,7 @@ void D_DoomMain(void) #ifdef _WIN32 //! + // @category obscure // @platform windows // @vanilla // @@ -486,6 +487,14 @@ void D_DoomMain(void) CheckRecordFrom(); + //! + // @arg + // @category demo + // @vanilla + // + // Record a demo named x.lmp. + // + p = M_CheckParm("-record"); if (p && p < myargc - 1) { @@ -509,6 +518,7 @@ void D_DoomMain(void) } //! + // @category game // @arg // @vanilla // @@ -549,6 +559,7 @@ static void HandleArgs(void) int p; //! + // @category game // @vanilla // // Disable monsters. @@ -557,6 +568,7 @@ static void HandleArgs(void) nomonsters = M_ParmExists("-nomonsters"); //! + // @category game // @vanilla // // Monsters respawn after being killed. @@ -583,6 +595,7 @@ static void HandleArgs(void) ravpic = M_ParmExists("-ravpic"); //! + // @category obscure // @vanilla // // Don't allow artifacts to be used when the run key is held down. @@ -608,6 +621,7 @@ static void HandleArgs(void) W_ParseCommandLine(); //! + // @category obscure // @vanilla // @arg // @@ -623,6 +637,7 @@ static void HandleArgs(void) } //! + // @category game // @arg // @vanilla // @@ -723,6 +738,14 @@ static void WarpCheck(void) int p; int map; + //! + // @category game + // @arg x + // @vanilla + // + // Start a game immediately, warping to MAPx. + // + p = M_CheckParm("-warp"); if (p && p < myargc - 1) { @@ -1044,6 +1067,14 @@ static void CheckRecordFrom(void) { int p; + //! + // @vanilla + // @category demo + // @arg + // + // Record a demo, loading from the given filename. Equivalent + // to -loadgame -record . + // p = M_CheckParm("-recordfrom"); if (!p || p > myargc - 2) { // Bad args diff --git a/src/i_sdlmusic.c b/src/i_sdlmusic.c index d485edd4..412fbf9d 100644 --- a/src/i_sdlmusic.c +++ b/src/i_sdlmusic.c @@ -921,6 +921,7 @@ static boolean I_SDL_InitMusic(void) int i; //! + // @category obscure // @arg // // Read all MIDI files from loaded WAD files, dump an example substitution diff --git a/src/i_system.c b/src/i_system.c index f72eaf26..681ecd4c 100644 --- a/src/i_system.c +++ b/src/i_system.c @@ -131,6 +131,7 @@ byte *I_ZoneBase (int *size) int p; //! + // @category obscure // @arg // // Specify the heap size, in MiB (default 16). @@ -306,6 +307,8 @@ void I_Error (char *error, ...) } //! + // @category obscure + // // If specified, don't show a GUI window for error messages when the // game exits with an error. // diff --git a/src/strife/d_main.c b/src/strife/d_main.c index ef1aec00..ef8b15ad 100644 --- a/src/strife/d_main.c +++ b/src/strife/d_main.c @@ -1571,6 +1571,7 @@ void D_DoomMain (void) } //! + // @category game // @vanilla // // Disable monsters. @@ -1579,6 +1580,7 @@ void D_DoomMain (void) nomonsters = M_CheckParm ("-nomonsters"); //! + // @category obscure // @vanilla // // Set Rogue playtesting mode (godmode, noclip toggled by backspace) @@ -1587,6 +1589,7 @@ void D_DoomMain (void) workparm = M_CheckParm ("-work"); //! + // @category obscure // @vanilla // // Flip player gun sprites (broken). @@ -1595,6 +1598,7 @@ void D_DoomMain (void) flipparm = M_CheckParm ("-flip"); //! + // @category game // @vanilla // // Respawn monsters after they are killed. @@ -1603,6 +1607,7 @@ void D_DoomMain (void) respawnparm = M_CheckParm ("-respawn"); //! + // @category game // @vanilla // // Items respawn at random locations @@ -1611,6 +1616,7 @@ void D_DoomMain (void) randomparm = M_CheckParm ("-random"); //! + // @category game // @vanilla // // Monsters move faster. @@ -1647,6 +1653,7 @@ void D_DoomMain (void) #ifdef _WIN32 //! + // @category obscure // @platform windows // @vanilla // @@ -1670,6 +1677,7 @@ void D_DoomMain (void) } //! + // @category game // @arg // @vanilla // @@ -1884,6 +1892,7 @@ void D_DoomMain (void) autostart = false; //! + // @category game // @arg // @vanilla // @@ -1901,6 +1910,7 @@ void D_DoomMain (void) // [STRIFE] no such thing in Strife // + // // @category game // // @arg // // @vanilla // // @@ -1949,6 +1959,7 @@ void D_DoomMain (void) } //! + // @category game // @arg x // @vanilla // @@ -1989,6 +2000,7 @@ void D_DoomMain (void) // can override it or send the load slot to other players. //! + // @category game // @arg // @vanilla // diff --git a/src/w_file.c b/src/w_file.c index 8f5e146f..feb5772f 100644 --- a/src/w_file.c +++ b/src/w_file.c @@ -52,6 +52,8 @@ wad_file_t *W_OpenFile(char *path) int i; //! + // @category obscure + // // Use the OS's virtual memory subsystem to map WAD files // directly into memory. //