Upgrade lua enumeration handling (scp-fs2open#7423)

* upgrade lua enumeration handling

* some cleanup

* add lua enum descriptions

* minor fixes

* Update code/scripting/api/objs/enums.cpp

Co-authored-by: John Fernandez <jafernandez.tampabay@gmail.com>

* include name

---------

Co-authored-by: John Fernandez <jafernandez.tampabay@gmail.com>

Author: MjnMixael

code/scripting/api/libs/async.cpp

@@ -396,8 +396,8 @@ ADE_FUNC(captureGameState,
 
 ADE_FUNC(createLuaState,
 	l_Async_Context,
-	"function() => enumeration",
-	"Creates an execution state by storing the passed function and calling that when the state is required.",
+	"function() => enumeration /* CONTEXT_* */",
+	"Creates an execution state by storing the passed function and calling that when the state is required. The function must return a CONTEXT_* enumeration.",
 	"execution_context",
 	"The execution context or invalid handle on error")
 {

code/scripting/api/libs/audio.cpp

@@ -341,7 +341,7 @@ ADE_FUNC(pauseMusic,
 
 ADE_FUNC(openAudioStream,
 	l_Audio,
-	"string fileName, enumeration stream_type /* AUDIOSTREAM_* values */",
+	"string fileName, enumeration stream_type /* AUDIOSTREAM_* */",
 	"Opens an audio stream of the specified file and type. An audio stream is meant for more long time sounds since "
 	"they are streamed from the file instead of loaded in its entirety.",
 	"audio_stream",

code/scripting/api/libs/base.cpp

@@ -396,8 +396,8 @@ ADE_FUNC(savePlayer, l_Base, "player plr", "Saves the specified player.", "boole
 
 ADE_FUNC(setControlMode,
 	l_Base,
-	"nil|enumeration mode /* LE_*_CONTROL */",
-	"Sets the current control mode for the game.",
+	"nil|enumeration mode /* FLIGHT_CONTROL_* */",
+	"Sets the current flight control mode for the game.",
 	"string",
 	"Current control mode")
 {
@@ -437,8 +437,8 @@ ADE_FUNC(setControlMode,
 
 ADE_FUNC(setButtonControlMode,
 	l_Base,
-	"nil|enumeration mode /* LE_*_BUTTON_CONTROL */",
-	"Sets the current control mode for the game.",
+	"nil|enumeration mode /* BUTTON_CONTROL_* */",
+	"Sets the current button control mode for the game.",
 	"string",
 	"Current control mode")
 {

code/scripting/api/libs/controls.cpp

@@ -75,9 +75,8 @@ ADE_FUNC(getMouseY, l_Mouse, nullptr, "Gets Mouse Y pos", "number", "Mouse y pos
 
 ADE_FUNC(isMouseButtonDown,
 	l_Mouse,
-	"enumeration buttonCheck1 /* MOUSE_*_BUTTON */, [ enumeration buttonCheck2 /* MOUSE_*_BUTTON */, enumeration "
-	"buttonCheck3 /* MOUSE_*_BUTTON */ ]",
-	"Returns whether the specified mouse buttons are up or down",
+	"enumeration buttonCheck1 /* MOUSE_* */, [enumeration buttonCheck2 /* MOUSE_* */, enumeration buttonCheck3 /* MOUSE_* */]",
+	"Returns whether the specified MOUSE_* buttons are up or down",
 	"boolean",
 	"Whether specified mouse buttons are down, or false if mouse is not initialized yet")
 {
@@ -115,8 +114,8 @@ ADE_FUNC(isMouseButtonDown,
 
 ADE_FUNC(mouseButtonDownCount,
 	l_Mouse,
-	"enumeration buttonCheck /* any one of MOUSE_LEFT_BUTTON, MOUSE_RIGHT_BUTTON, MOUSE_MIDDLE_BUTTON, MOUSE_X1_BUTTON, MOUSE_X2_BUTTON */, [ boolean reset_count ]",
-	"Returns the pressed count of the specified button.  The count is then reset, unless reset_count (which defaults to true) is false.",
+	"enumeration buttonCheck /* MOUSE_* */, [boolean reset_count]",
+	"Returns the pressed count of the specified MOUSE_* button.  The count is then reset, unless reset_count (which defaults to true) is false.",
 	"number",
 	"The number of frames this button has been pressed, or -1 if the mouse has not been initialized")
 {
@@ -315,7 +314,7 @@ ADE_FUNC(AxisInverted, l_Mouse, "number cid, number axis, boolean inverted", "Ge
 		return ADE_RETURN_FALSE;
 }
 
-ADE_VIRTVAR(FlightCursorMode, l_Mouse, "enumeration FlightMode", "Flight Mode; uses LE_FLIGHTMODE_* enumerations.", "enumeration", "enumeration flight mode")
+ADE_VIRTVAR(FlightCursorMode, l_Mouse, "enumeration /* FLIGHTMODE_* */", "Flight Mode; uses FLIGHTMODE_* enumerations.", "enumeration", "Current flight cursor mode as a FLIGHTMODE_* enumeration")
 {
 	enum_h flightmode_arg;
 

code/scripting/api/libs/graphics.cpp

@@ -278,7 +278,7 @@ ADE_VIRTVAR(CurrentRenderTarget, l_Graphics, "texture", "Current rendering targe
 	}
 }
 
-ADE_VIRTVAR(CurrentResizeMode, l_Graphics, "enumeration ResizeMode", "Current resize mode; uses GR_RESIZE_* enumerations.  This resize mode will be used by the gr.* drawing methods.", "enumeration", nullptr)
+ADE_VIRTVAR(CurrentResizeMode, l_Graphics, "enumeration /* GR_RESIZE_* */", "Current resize mode; uses GR_RESIZE_* enumerations.  This resize mode will be used by the gr.* drawing methods.", "enumeration", nullptr)
 {
 	enum_h resize_arg;
 
@@ -1510,7 +1510,7 @@ ADE_FUNC(drawString, l_Graphics, "string|boolean Message, [number X1, number Y1,
 	return drawString_sub(L, false);
 }
 
-ADE_FUNC(drawStringResized, l_Graphics, "enumeration ResizeMode, string|boolean Message, [number X1, number Y1, number X2, number Y2]",
+ADE_FUNC(drawStringResized, l_Graphics, "enumeration ResizeMode /* GR_RESIZE_* */, string|boolean Message, [number X1, number Y1, number X2, number Y2]",
 	"Draws a string, scaled according to the GR_RESIZE_* parameter. Use x1/y1 to control position, x2/y2 to limit textbox size."
 	"Text will automatically move onto new lines, if x2/y2 is specified, however the line spacing will probably not be correct."
 	"Additionally, calling drawString with only a string argument will automatically"
@@ -2046,7 +2046,7 @@ ADE_FUNC(loadModel, l_Graphics, "string Filename", "Loads the model - will not s
 	return ade_set_args(L, "o", l_Model.Set(model_h(model_num)));
 }
 
-ADE_FUNC(hasViewmode, l_Graphics, "enumeration", "Specifies if the current viemode has the specified flag, see VM_* enumeration", "boolean", "true if flag is present, false otherwise")
+ADE_FUNC(hasViewmode, l_Graphics, "enumeration /* VM_* */", "Specifies if the current viewmode has the specified flag.", "boolean", "true if flag is present, false otherwise")
 {
 	enum_h *type = NULL;
 
@@ -2145,7 +2145,7 @@ ADE_FUNC(hasViewmode, l_Graphics, "enumeration", "Specifies if the current viemo
 	return ade_set_args(L, "b", (Viewer_mode & bit) != 0);
 }
 
-ADE_FUNC(setClip, l_Graphics, "number x, number y, number width, number height, [enumeration ResizeMode]", "Sets the clipping region to the specified rectangle. Most drawing functions are able to handle the offset.", "boolean", "true if successful, false otherwise")
+ADE_FUNC(setClip, l_Graphics, "number x, number y, number width, number height, [enumeration /* GR_RESIZE_* */]", "Sets the clipping region to the specified rectangle using GR_RESIZE_* enumerations. Most drawing functions are able to handle the offset.", "boolean", "true if successful, false otherwise")
 {
 	int x, y, width, height;
 	enum_h resize_arg;

code/scripting/api/libs/hud.cpp

@@ -260,7 +260,7 @@ ADE_FUNC(getHUDGaugeHandle, l_HUD, "string Name", "Returns a handle to a specifi
 		return ade_set_args(L, "o", l_HudGauge.Set(gauge));
 }
 
-ADE_FUNC(flashTargetBox, l_HUD, "enumeration section, [number duration_in_milliseconds]", "Flashes a section of the target box with a default duration of " SCP_TOKEN_TO_STR(TBOX_FLASH_DURATION) " milliseconds", nullptr, nullptr)
+ADE_FUNC(flashTargetBox, l_HUD, "enumeration section /* TBOX_* */, [number duration_in_milliseconds]", "Flashes a section of the target box with a default duration of " SCP_TOKEN_TO_STR(TBOX_FLASH_DURATION) " milliseconds", nullptr, nullptr)
 {
 	enum_h section;
 	int num_args, duration;

code/scripting/api/libs/mission.cpp

@@ -1055,9 +1055,9 @@ int sendMessage_sub(lua_State* L, const void* sender, int messageSource, int mes
 
 ADE_FUNC(sendMessage,
 	l_Mission,
-	"string|ship sender, message message, [number delay=0.0, enumeration priority = MESSAGE_PRIORITY_NORMAL, boolean "
+	"string|ship sender, message message, [number delay=0.0, enumeration priority = MESSAGE_PRIORITY_NORMAL /* MESSAGE_PRIORITY_* */, boolean "
 	"fromCommand = false]",
-	"Sends a message from the given source or ship with the given priority, or optionally sends it from the "
+	"Sends a message from the given source or ship with the given MESSAGE_PRIORITY_* priority, or optionally sends it from the "
 	"mission's command source.<br>"
 	"If delay is specified, the message will be delayed by the specified time in seconds.<br>"
 	"If sender is <i>nil</i> the message will not have a sender.  If sender is a ship object the message will be sent from the ship; "
@@ -1266,10 +1266,10 @@ int getBuiltinMessageType(const enum_h* enumValue)
 
 ADE_FUNC(sendBuiltinMessage,
 	l_Mission,
-	"ship sender, ship subject, enumeration|string type_or_type_name",
+	"ship sender, ship subject, enumeration|string type_or_type_name /* BUILTIN_MESSAGE_* */",
 	"Sends one of the builtin messages from the given source or ship, taking the message subject into account."
 	"The subject can be nil or it can be the target of the message like a response to a destroy order."
-	"The type must be one of the BUILTIN_MESSAGE enumerations or a string matching a custom built-in message defined in messages.tbl.",
+	"The type must be one of the BUILTIN_MESSAGE_* enumerations or a string matching a custom built-in message defined in messages.tbl.",
 	"boolean",
 	"true if successful, false otherwise")
 {
@@ -1323,9 +1323,9 @@ ADE_FUNC(sendBuiltinMessage,
 
 ADE_FUNC(addMessageToScrollback,
 	l_Mission,
-	"string message, [team|enumeration source=HUD_SOURCE_COMPUTER]",
+	"string message, [team|enumeration source = SCROLLBACK_SOURCE_COMPUTER /* SCROLLBACK_* */]",
 	"Adds a string to the message log scrollback without sending it as a message first. Source should be either the team handle "
-	"or one of the SCROLLBACK_SOURCE enumerations.",
+	"or one of the SCROLLBACK_* enumerations.",
 	"boolean",
 	"true if successful, false otherwise")
 {
@@ -1894,8 +1894,8 @@ ADE_FUNC(getMissionFilename, l_Mission, NULL, "Gets mission filename", "string",
 
 ADE_FUNC(startMission,
 	l_Mission,
-	"string|enumeration mission /* Filename or MISSION_* enumeration */, [boolean Briefing = true]",
-	"Starts the defined mission",
+	"string|enumeration mission /* MISSION_* */, [boolean Briefing = true]",
+	"Starts the defined mission. Pass a filename string or a MISSION_* enumeration.",
 	"boolean",
 	"True, or false if the function fails")
 {
@@ -2707,7 +2707,7 @@ ADE_FUNC(hasDebriefing,
 	return ade_set_args(L, "b", !(The_mission.flags[Mission::Mission_Flags::Toggle_debriefing]));
 }
 
-ADE_FUNC(getMusicScore, l_Mission, "enumeration score", "Returns the music.tbl entry name for the specified mission music score", "string", "The name, or nil if the score is invalid")
+ADE_FUNC(getMusicScore, l_Mission, "enumeration score /* SCORE_* */", "Returns the music.tbl entry name for the specified mission music score", "string", "The name, or nil if the score is invalid")
 {
 	enum_h score;
 	if (!ade_get_args(L, "o", l_Enum.Get(&score)))
@@ -2728,7 +2728,7 @@ ADE_FUNC(getMusicScore, l_Mission, "enumeration score", "Returns the music.tbl e
 	return ade_set_args(L, "s", name);
 }
 
-ADE_FUNC(setMusicScore, l_Mission, "enumeration score, string name", "Sets the music.tbl entry for the specified mission music score", nullptr, nullptr)
+ADE_FUNC(setMusicScore, l_Mission, "enumeration score /* SCORE_* */, string name", "Sets the music.tbl entry for the specified mission music score", nullptr, nullptr)
 {
 	enum_h score;
 	const char *name;

code/scripting/api/libs/testing.cpp

@@ -33,7 +33,7 @@ ADE_LIB(l_Testing, "Testing", "ts", "Experimental or testing stuff");
 
 ADE_FUNC(openAudioStreamMem,
 	l_Testing,
-	"string snddata, enumeration stream_type /* AUDIOSTREAM_* values */",
+	"string snddata, enumeration stream_type /* AUDIOSTREAM_* */",
 	"Opens an audio stream of the specified in-memory file contents and type.",
 	"audio_stream",
 	"A handle to the opened stream or invalid on error")

code/scripting/api/libs/ui.cpp

@@ -237,7 +237,7 @@ ADE_FUNC(playElementSound,
 	return ade_set_args(L, "b", scpui::SoundPlugin::instance()->PlayElementSound(el, event, state));
 }
 
-ADE_FUNC(maybePlayCutscene, l_UserInterface, "enumeration MovieType, boolean RestartMusic, number ScoreIndex", "Plays a cutscene, if one exists, for the appropriate state transition.  If RestartMusic is true, then the music score at ScoreIndex will be started after the cutscene plays.", nullptr, "Returns nothing")
+ADE_FUNC(maybePlayCutscene, l_UserInterface, "enumeration MovieType /* MOVIE_* */, boolean RestartMusic, number ScoreIndex", "Plays a cutscene, if one exists, for the appropriate state transition.  If RestartMusic is true, then the music score at ScoreIndex will be started after the cutscene plays.", nullptr, "Returns nothing")
 {
 	enum_h movie_type;
 	bool restart_music = false;
@@ -821,9 +821,9 @@ ADE_FUNC(skipTraining,
 ADE_FUNC(commitToMission,
 	l_UserInterface_Brief,
 	nullptr,
-	"Commits to the current mission with current loadout data, and starts the mission. Returns one of the COMMIT_ enums to indicate any errors.",
+	"Commits to the current mission with current loadout data, and starts the mission.",
 	"enumeration",
-	"the error value")
+	"A COMMIT_* enumeration indicating any errors")
 {
 	commit_pressed_status rc;
 
@@ -3447,8 +3447,8 @@ ADE_FUNC(setName,
 
 ADE_FUNC(setGameType,
 	l_UserInterface_MultiStartGame,
-	"enumeration type=MULTI_GAME_TYPE_OPEN, [string | number password_or_rank_index]",
-	"Sets the game's type and, optionally, the password or rank index.",
+	"enumeration type = MULTI_GAME_TYPE_OPEN /* MULTI_GAME_TYPE_* */, [string | number password_or_rank_index]",
+	"Sets the game type and optionally the password or rank index.",
 	"boolean",
 	"True if successful, false otherwise")
 {