ref: ceefa5bbd95c97d5299f8a81f6ce83a1ae83c55b
parent: 04b3ca24ebb9d2a976e4adcdfb8212072b3d9794
author: Simon Howard <fraggle@soulsphere.org>
date: Fri Mar 16 17:20:55 EDT 2018
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.
--- a/man/docgen
+++ b/man/docgen
@@ -157,14 +157,16 @@
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 @@
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 @@
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])
+ documentation_targets = [c for _, c in categories]
- for c in categories:
- if c != None:
- documentation_targets.append(categories[c])
-
# Generate the output
-
output_function(documentation_targets, substs, template)
--- a/src/doom/d_main.c
+++ b/src/doom/d_main.c
@@ -1286,6 +1286,7 @@
}
//!
+ // @category game
// @vanilla
//
// Disable monsters.
@@ -1294,6 +1295,7 @@
nomonsters = M_CheckParm ("-nomonsters");//!
+ // @category game
// @vanilla
//
// Monsters respawn after being killed.
@@ -1302,6 +1304,7 @@
respawnparm = M_CheckParm ("-respawn");//!
+ // @category game
// @vanilla
//
// Monsters move faster.
@@ -1309,10 +1312,10 @@
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 @@
#ifdef _WIN32
//!
+ // @category obscure
// @platform windows
// @vanilla
//
@@ -1371,6 +1375,7 @@
}
//!
+ // @category game
// @arg <x>
// @vanilla
//
@@ -1683,6 +1688,7 @@
autostart = false;
//!
+ // @category game
// @arg <skill>
// @vanilla
//
@@ -1699,6 +1705,7 @@
}
//!
+ // @category game
// @arg <n>
// @vanilla
//
@@ -1746,6 +1753,7 @@
}
//!
+ // @category game
// @arg [<x> <y> | <xy>]
// @vanilla
//
@@ -1793,6 +1801,7 @@
// can override it or send the load slot to other players.
//!
+ // @category game
// @arg <s>
// @vanilla
//
--- a/src/heretic/d_main.c
+++ b/src/heretic/d_main.c
@@ -737,6 +737,7 @@
I_AtExit(D_Endoom, false);
//!
+ // @category game
// @vanilla
//
// Disable monsters.
@@ -745,6 +746,7 @@
nomonsters = M_ParmExists("-nomonsters");//!
+ // @category game
// @vanilla
//
// Monsters respawn after being killed.
@@ -761,6 +763,7 @@
ravpic = M_ParmExists("-ravpic");//!
+ // @category obscure
// @vanilla
//
// Allow artifacts to be used when the run key is held down.
@@ -791,6 +794,7 @@
}
//!
+ // @category game
// @arg <skill>
// @vanilla
//
@@ -806,6 +810,7 @@
}
//!
+ // @category game
// @arg <n>
// @vanilla
//
@@ -821,6 +826,7 @@
}
//!
+ // @category game
// @arg <x> <y>
// @vanilla
//
@@ -848,6 +854,7 @@
#ifdef _WIN32
//!
+ // @category obscure
// @platform windows
// @vanilla
//
@@ -1102,6 +1109,7 @@
}
//!
+ // @category game
// @arg <s>
// @vanilla
//
--- a/src/hexen/h2_main.c
+++ b/src/hexen/h2_main.c
@@ -371,6 +371,7 @@
#ifdef _WIN32
//!
+ // @category obscure
// @platform windows
// @vanilla
//
@@ -486,6 +487,14 @@
CheckRecordFrom();
+ //!
+ // @arg <x>
+ // @category demo
+ // @vanilla
+ //
+ // Record a demo named x.lmp.
+ //
+
p = M_CheckParm("-record");if (p && p < myargc - 1)
{@@ -509,6 +518,7 @@
}
//!
+ // @category game
// @arg <s>
// @vanilla
//
@@ -549,6 +559,7 @@
int p;
//!
+ // @category game
// @vanilla
//
// Disable monsters.
@@ -557,6 +568,7 @@
nomonsters = M_ParmExists("-nomonsters");//!
+ // @category game
// @vanilla
//
// Monsters respawn after being killed.
@@ -583,6 +595,7 @@
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 @@
W_ParseCommandLine();
//!
+ // @category obscure
// @vanilla
// @arg <path>
//
@@ -623,6 +637,7 @@
}
//!
+ // @category game
// @arg <skill>
// @vanilla
//
@@ -723,6 +738,14 @@
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 @@
{int p;
+ //!
+ // @vanilla
+ // @category demo
+ // @arg <savenum> <demofile>
+ //
+ // Record a demo, loading from the given filename. Equivalent
+ // to -loadgame <savenum> -record <demofile>.
+ //
p = M_CheckParm("-recordfrom");if (!p || p > myargc - 2)
{ // Bad args--- a/src/i_sdlmusic.c
+++ b/src/i_sdlmusic.c
@@ -921,6 +921,7 @@
int i;
//!
+ // @category obscure
// @arg <filename>
//
// Read all MIDI files from loaded WAD files, dump an example substitution
--- a/src/i_system.c
+++ b/src/i_system.c
@@ -131,6 +131,7 @@
int p;
//!
+ // @category obscure
// @arg <mb>
//
// Specify the heap size, in MiB (default 16).
@@ -306,6 +307,8 @@
}
//!
+ // @category obscure
+ //
// If specified, don't show a GUI window for error messages when the
// game exits with an error.
//
--- a/src/strife/d_main.c
+++ b/src/strife/d_main.c
@@ -1571,6 +1571,7 @@
}
//!
+ // @category game
// @vanilla
//
// Disable monsters.
@@ -1579,6 +1580,7 @@
nomonsters = M_CheckParm ("-nomonsters");//!
+ // @category obscure
// @vanilla
//
// Set Rogue playtesting mode (godmode, noclip toggled by backspace)
@@ -1587,6 +1589,7 @@
workparm = M_CheckParm ("-work");//!
+ // @category obscure
// @vanilla
//
// Flip player gun sprites (broken).
@@ -1595,6 +1598,7 @@
flipparm = M_CheckParm ("-flip");//!
+ // @category game
// @vanilla
//
// Respawn monsters after they are killed.
@@ -1603,6 +1607,7 @@
respawnparm = M_CheckParm ("-respawn");//!
+ // @category game
// @vanilla
//
// Items respawn at random locations
@@ -1611,6 +1616,7 @@
randomparm = M_CheckParm ("-random");//!
+ // @category game
// @vanilla
//
// Monsters move faster.
@@ -1647,6 +1653,7 @@
#ifdef _WIN32
//!
+ // @category obscure
// @platform windows
// @vanilla
//
@@ -1670,6 +1677,7 @@
}
//!
+ // @category game
// @arg <x>
// @vanilla
//
@@ -1884,6 +1892,7 @@
autostart = false;
//!
+ // @category game
// @arg <skill>
// @vanilla
//
@@ -1901,6 +1910,7 @@
// [STRIFE] no such thing in Strife
//
+ // // @category game
// // @arg <n>
// // @vanilla
// //
@@ -1949,6 +1959,7 @@
}
//!
+ // @category game
// @arg x
// @vanilla
//
@@ -1989,6 +2000,7 @@
// can override it or send the load slot to other players.
//!
+ // @category game
// @arg <s>
// @vanilla
//
--- a/src/w_file.c
+++ b/src/w_file.c
@@ -52,6 +52,8 @@
int i;
//!
+ // @category obscure
+ //
// Use the OS's virtual memory subsystem to map WAD files
// directly into memory.
//