Add missing names to lua return values. Additional return description and overload cleanup.

rts/Lua/LuaHandle.cpp

@@ -2651,7 +2651,7 @@ void CLuaHandle::SunChanged()
  * @param type "unit"|"feature" The type of the object pointed at.
  * @param id integer The `unitID` or `featureID`.
  * @param cmd integer The current command ID.
- * @return integer The command ID to use as the default, or nil to keep the current ID.
+ * @return integer commandId The command ID to use as the default, or nil to keep the current ID.
  */
 bool CLuaHandle::DefaultCommand(const CUnit* unit,
                                 const CFeature* feature, int& cmd)
@@ -3704,7 +3704,7 @@ void CLuaHandle::MiniMapGeometryChanged(const int2 newPos, const int2 newDim, co
  * @param cmdID integer
  * @param cmdParams table
  * @param options CommandOptions
- * @return boolean Returning true deletes the command and does not send it through the network.
+ * @return boolean delete Returning true deletes the command and does not send it through the network.
  */
 bool CLuaHandle::CommandNotify(const Command& cmd)
 {

rts/Lua/LuaHandleSynced.cpp

@@ -579,7 +579,7 @@ bool CSyncedLuaHandle::SyncedActionFallback(const std::string& msg, int playerID
  * @param cmdParams number[]
  * @param cmdOptions CommandOptions
  * @param cmdTag number
- * @return boolean whether to remove the command from the queue
+ * @return boolean removeCmd whether to remove the command from the queue
  */
 bool CSyncedLuaHandle::CommandFallback(const CUnit* unit, const Command& cmd)
 {
@@ -617,7 +617,7 @@ bool CSyncedLuaHandle::CommandFallback(const CUnit* unit, const Command& cmd)
  * @param cmdTag number
  * @param synced boolean
  * @param fromLua boolean
- * @return boolean whether it should be let into the queue.
+ * @return boolean allowCmd whether it should be let into the queue.
  */
 bool CSyncedLuaHandle::AllowCommand(const CUnit* unit, const Command& cmd, int playerNum, bool fromSynced, bool fromLua)
 {
@@ -656,7 +656,8 @@ bool CSyncedLuaHandle::AllowCommand(const CUnit* unit, const Command& cmd, int p
  * @param y number
  * @param z number
  * @param facing FacingInteger
- * @return boolean allow, boolean dropOrder
+ * @return boolean allow
+ * @return boolean dropOrder
  */
 std::pair <bool, bool> CSyncedLuaHandle::AllowUnitCreation(
 	const UnitDef* unitDef,
@@ -701,7 +702,7 @@ std::pair <bool, bool> CSyncedLuaHandle::AllowUnitCreation(
  * @param oldTeam integer
  * @param newTeam integer
  * @param capture boolean
- * @return boolean whether or not the transfer is permitted.
+ * @return boolean allow whether or not the transfer is permitted.
  */
 bool CSyncedLuaHandle::AllowUnitTransfer(const CUnit* unit, int newTeam, bool capture)
 {
@@ -738,7 +739,7 @@ bool CSyncedLuaHandle::AllowUnitTransfer(const CUnit* unit, int newTeam, bool ca
  * @param unitID integer
  * @param unitDefID integer
  * @param part number
- * @return boolean whether or not the build makes progress.
+ * @return boolean allow whether or not the build makes progress.
  */
 bool CSyncedLuaHandle::AllowUnitBuildStep(const CUnit* builder, const CUnit* unit, float part)
 {
@@ -775,7 +776,7 @@ bool CSyncedLuaHandle::AllowUnitBuildStep(const CUnit* builder, const CUnit* uni
  * @param unitID integer
  * @param unitDefID integer
  * @param part number
- * @return boolean whether or not the capture makes progress.
+ * @return boolean allow whether or not the capture makes progress.
  */
 bool CSyncedLuaHandle::AllowUnitCaptureStep(const CUnit* builder, const CUnit* unit, float part)
 {
@@ -813,7 +814,7 @@ bool CSyncedLuaHandle::AllowUnitCaptureStep(const CUnit* builder, const CUnit* u
  * @param transporteeID integer
  * @param transporteeUnitDefID integer
  * @param transporteeTeam integer
- * @return boolean whether or not the transport is allowed
+ * @return boolean allow whether or not the transport is allowed
  */
 bool CSyncedLuaHandle::AllowUnitTransport(const CUnit* transporter, const CUnit* transportee)
 {
@@ -854,7 +855,7 @@ bool CSyncedLuaHandle::AllowUnitTransport(const CUnit* transporter, const CUnit*
  * @param x number
  * @param y number
  * @param z number
- * @return boolean whether or not the transport load is allowed
+ * @return boolean allow whether or not the transport load is allowed
  */
 bool CSyncedLuaHandle::AllowUnitTransportLoad(
 	const CUnit* transporter,
@@ -904,7 +905,7 @@ bool CSyncedLuaHandle::AllowUnitTransportLoad(
  * @param x number
  * @param y number
  * @param z number
- * @return boolean whether or not the transport unload is allowed
+ * @return boolean allow whether or not the transport unload is allowed
  */
 bool CSyncedLuaHandle::AllowUnitTransportUnload(
 	const CUnit* transporter,
@@ -945,7 +946,7 @@ bool CSyncedLuaHandle::AllowUnitTransportUnload(
  * @function SyncedCallins:AllowUnitCloak
  * @param unitID integer
  * @param enemyID integer?
- * @return boolean whether unit is allowed to cloak
+ * @return boolean allow whether unit is allowed to cloak
  */
 bool CSyncedLuaHandle::AllowUnitCloak(const CUnit* unit, const CUnit* enemy)
 {
@@ -982,7 +983,7 @@ bool CSyncedLuaHandle::AllowUnitCloak(const CUnit* unit, const CUnit* enemy)
  * @param unitID integer
  * @param objectID integer?
  * @param weaponNum number?
- * @return boolean whether unit is allowed to decloak
+ * @return boolean allow whether unit is allowed to decloak
  */
 bool CSyncedLuaHandle::AllowUnitDecloak(const CUnit* unit, const CSolidObject* object, const CWeapon* weapon)
 {
@@ -1025,7 +1026,7 @@ bool CSyncedLuaHandle::AllowUnitDecloak(const CUnit* unit, const CSolidObject* o
  * @function SyncedCallins:AllowUnitKamikaze
  * @param unitID integer
  * @param targetID integer
- * @return boolean whether unit is allowed to selfd
+ * @return boolean allow whether unit is allowed to selfd
  */
 bool CSyncedLuaHandle::AllowUnitKamikaze(const CUnit* unit, const CUnit* target, bool allowed)
 {
@@ -1058,7 +1059,7 @@ bool CSyncedLuaHandle::AllowUnitKamikaze(const CUnit* unit, const CUnit* target,
  * @param x number
  * @param y number
  * @param z number
- * @return boolean whether or not the creation is permitted
+ * @return boolean allow whether or not the creation is permitted
  */
 bool CSyncedLuaHandle::AllowFeatureCreation(const FeatureDef* featureDef, int teamID, const float3& pos)
 {
@@ -1103,7 +1104,7 @@ bool CSyncedLuaHandle::AllowFeatureCreation(const FeatureDef* featureDef, int te
  * @param featureDefID integer
  * @param part number
  *
- * @return boolean whether or not the change is permitted
+ * @return boolean allow whether or not the change is permitted
  */
 bool CSyncedLuaHandle::AllowFeatureBuildStep(const CUnit* builder, const CFeature* feature, float part)
 {
@@ -1138,7 +1139,7 @@ bool CSyncedLuaHandle::AllowFeatureBuildStep(const CUnit* builder, const CFeatur
  * @param teamID integer
  * @param res string
  * @param level number
- * @return boolean whether or not the sharing level is permitted
+ * @return boolean allow whether or not the sharing level is permitted
  */
 bool CSyncedLuaHandle::AllowResourceLevel(int teamID, const std::string& type, float level)
 {
@@ -1172,7 +1173,7 @@ bool CSyncedLuaHandle::AllowResourceLevel(int teamID, const std::string& type, f
  * @param newTeamID integer
  * @param res string
  * @param amount number
- * @return boolean whether or not the transfer is permitted.
+ * @return boolean allow whether or not the transfer is permitted.
  */
 bool CSyncedLuaHandle::AllowResourceTransfer(int oldTeam, int newTeam, const char* type, float amount)
 {
@@ -1204,7 +1205,7 @@ bool CSyncedLuaHandle::AllowResourceTransfer(int oldTeam, int newTeam, const cha
  *
  * @function SyncedCallins:ResourceExcess
  * @param excesses table
- * @return boolean whether or not Lua handled the event
+ * @return boolean handled whether or not Lua handled the event
  */
 bool CSyncedLuaHandle::ResourceExcess(const std::map <int, SResourcePack>& excesses)
 {
@@ -1381,7 +1382,7 @@ bool CSyncedLuaHandle::AllowStartPosition(int playerID, int teamID, unsigned cha
  * @param unitTeam integer
  * @param data number was supposed to indicate the type of notification but currently never has a value other than 1 ("unit hit the ground").
  *
- * @return boolean whether or not the unit should remain script-controlled (false) or return to engine controlled movement (true).
+ * @return boolean engineControl whether or not the unit should remain script-controlled (false) or return to engine controlled movement (true).
  */
 bool CSyncedLuaHandle::MoveCtrlNotify(const CUnit* unit, int data)
 {
@@ -1419,7 +1420,7 @@ bool CSyncedLuaHandle::MoveCtrlNotify(const CUnit* unit, int data)
  * @param buildUnitID integer
  * @param buildUnitDefID integer
  * @param buildUnitTeam integer
- * @return boolean if true the current build order is terminated
+ * @return boolean stop if true the current build order is terminated
  */
 bool CSyncedLuaHandle::TerraformComplete(const CUnit* unit, const CUnit* build)
 {
@@ -1489,7 +1490,8 @@ bool CSyncedLuaHandle::TerraformComplete(const CUnit* unit, const CUnit* build)
  * @param attackerDefID integer? Synced Only
  * @param attackerTeam integer? Synced Only
  *
- * @return number newDamage, number impulseMult
+ * @return number newDamage
+ * @return number impulseMult
  */
 bool CSyncedLuaHandle::UnitPreDamaged(
 	const CUnit* unit,
@@ -1665,7 +1667,7 @@ bool CSyncedLuaHandle::FeaturePreDamaged(
  * @param hitY number
  * @param hitZ number
  *
- * @return boolean if true the gadget handles the collision event and the engine does not remove the projectile
+ * @return boolean handle if true the gadget handles the collision event and the engine does not remove the projectile
  */
 bool CSyncedLuaHandle::ShieldPreDamaged(
 	const CProjectile* projectile,
@@ -1787,7 +1789,7 @@ int CSyncedLuaHandle::AllowWeaponTargetCheck(unsigned int attackerID, unsigned i
  * @param defPriority number
  *
  * @return boolean allowed
- * @return number the new priority for this target (if you don't want to change it, return defPriority). Lower priority targets are targeted first.
+ * @return number newPriority the new priority for this target (if you don't want to change it, return defPriority). Lower priority targets are targeted first.
  *
  * @see Script.SetWatchAllowTarget
  * @see Script.SetWatchWeapon
@@ -2222,7 +2224,7 @@ GetWatchDef(Synced, Feature)
  * ```
  *
  * @param weaponDefID integer
- * @return boolean watched True if watch is enabled for any weaponDefID callins.
+ * @return boolean watched `true` if watch is enabled for any weaponDefID callins.
  *
  * @see Script.SetWatchWeapon
  */

rts/Lua/LuaMathExtra.cpp

@@ -64,7 +64,7 @@ bool LuaMathExtra::PushEntries(lua_State* L)
  * @function math.hypot
  * @param x number
  * @param y number
- * @return number `sqrt(x*x+y*y)`
+ * @return number hypotenuse `sqrt(x*x+y*y)`
  */
 int LuaMathExtra::hypot(lua_State* L) {
 	RECOIL_DETAILED_TRACY_ZONE;
@@ -146,7 +146,7 @@ int LuaMathExtra::sgn(lua_State* L) {
  * @param x number
  * @param y number
  * @param a number
- * @return number (x+(y-x)*a)
+ * @return number # (x+(y-x)*a)
  */
 int LuaMathExtra::mix(lua_State* L) {
 	RECOIL_DETAILED_TRACY_ZONE;

rts/Lua/LuaOpenGL.cpp

@@ -5685,22 +5685,22 @@ int LuaOpenGL::PushPopMatrix(lua_State* L)
  * @function gl.GetMatrixData
  * @param type GL Matrix type (`GL.PROJECTION`, `GL.MODELVIEW`, `GL.TEXTURE`).
  * @param index integer Matrix index in range `[1, 16]`.
- * @return number The value.
+ * @return number value The value at the given index.
  */
 /***
  * @function gl.GetMatrixData
  * @param type GL Matrix type (`GL.PROJECTION`, `GL.MODELVIEW`, `GL.TEXTURE`).
- * @return Matrix4x4 The matrix.
+ * @return Matrix4x4 matrix The matrix.
  */
 /***
  * @function gl.GetMatrixData
  * @param index integer Matrix index in range `[1, 16]`.
- * @return number The value.
+ * @return number value The value at the given index.
  */
 /***
  * @function gl.GetMatrixData
  * @param name MatrixName The matrix name.
- * @return Matrix4x4 The matrix.
+ * @return Matrix4x4 matrix The matrix.
  */
 int LuaOpenGL::GetMatrixData(lua_State* L)
 {
@@ -6295,7 +6295,7 @@ static void PushPixelData(lua_State* L, int fSize, const float*& data)
  * @param w 1
  * @param h 1
  * @param format GL? (Default: `GL.RGBA`)
- * @return number ... Color values (color size based on format).
+ * @return number[] color Color values (color size based on format).
  */
 /***
  * Get column of pixels.
@@ -6305,7 +6305,7 @@ static void PushPixelData(lua_State* L, int fSize, const float*& data)
  * @param w 1
  * @param h integer
  * @param format GL? (Default: `GL.RGBA`)
- * @return number[][] Column of color values (color size based on format).
+ * @return number[][] colors Column of color values (color size based on format).
  */
 /***
  * Get row of pixels.
@@ -6315,17 +6315,17 @@ static void PushPixelData(lua_State* L, int fSize, const float*& data)
  * @param w integer
  * @param h 1
  * @param format GL? (Default: `GL.RGBA`)
- * @return number[][] Row of color values (color size based on format).
+ * @return number[][] colors Row of color values (color size based on format).
  */
 /***
- * Get row of pixels.
+ * Get columns of pixels.
  * @function gl.ReadPixels
  * @param x integer
  * @param y integer
  * @param w integer
  * @param h integer
  * @param format GL? (Default: `GL.RGBA`)
- * @return number[][][] Array of columns of color values (color size based on format).
+ * @return number[][][] colors Array of columns of color values (color size based on format).
  */
 int LuaOpenGL::ReadPixels(lua_State* L)
 {
@@ -6610,7 +6610,7 @@ int LuaOpenGL::GetQuery(lua_State* L)
 
 /***
  * @function gl.GetGlobalTexNames
- * @return string[] List of texture names.
+ * @return string[] texNames List of texture names.
  */
 int LuaOpenGL::GetGlobalTexNames(lua_State* L)
 {

rts/Lua/LuaSyncedCtrl.cpp

@@ -975,7 +975,7 @@ int LuaSyncedCtrl::AssignPlayerToTeam(lua_State* L)
  * @param x number left position (elmos)
  * @param y number vertical position (elmos)
  * @param z number top position (elmos)
- * @return boolean true if the position was set, false if the teamID is invalid
+ * @return boolean success true if the position was set, false if the teamID is invalid
  */
 int LuaSyncedCtrl::SetTeamStartPosition(lua_State* L)
 {
@@ -1006,7 +1006,7 @@ int LuaSyncedCtrl::SetTeamStartPosition(lua_State* L)
  * @function Spring.SetPlayerReadyState
  * @param playerID integer
  * @param ready boolean
- * @return boolean true if the state was set, false if the playerID was invalid
+ * @return boolean success true if the state was set, false if the playerID was invalid
  */
 int LuaSyncedCtrl::SetPlayerReadyState(lua_State* L)
 {
@@ -1121,7 +1121,7 @@ int LuaSyncedCtrl::KillTeam(lua_State* L)
  * Pass multiple winners to declare a draw.
  * Pass no arguments if undecided (e.g. when dropped from the host).
  *
- * @return integer Number of accepted (valid) ally teams.
+ * @return integer teams Number of accepted (valid) ally teams.
  */
 int LuaSyncedCtrl::GameOver(lua_State* L)
 {
@@ -3546,7 +3546,7 @@ int LuaSyncedCtrl::SetUnitPhysicalStateBit(lua_State* L)
 /***
  * @function Spring.GetUnitPhysicalState
  * @param unitID integer
- * @return number Unit's PhysicalState bitmask
+ * @return number physicalState Unit's PhysicalState bitmask
  */
 int LuaSyncedCtrl::GetUnitPhysicalState(lua_State* L)
 {
@@ -3822,7 +3822,7 @@ int LuaSyncedCtrl::SetUnitPieceParent(lua_State* L)
  * @param unitID integer
  * @param pieceNum number
  * @param matrix number[] an array of 16 floats
- * @return boolean? valid - if the matrix can be used for the purpose of defining the piece spatial transformation. Blocks the piece animation, if true.
+ * @return boolean? valid whether the matrix can be used for the purpose of defining the piece spatial transformation. Blocks the piece animation, if true.
  */
 int LuaSyncedCtrl::SetUnitPieceMatrix(lua_State* L)
 {
@@ -3911,7 +3911,7 @@ int LuaSyncedCtrl::SetUnitPieceVisible(lua_State* L)
  * @param unitID integer
  * @param type "los"|"airLos"|"radar"|"sonar"|"seismic"|"radarJammer"|"sonarJammer"
  * @param radius number
- * @return number? New radius, or `nil` if unit is invalid.
+ * @return number? newRadius New radius, or `nil` if unit is invalid.
  */
 int LuaSyncedCtrl::SetUnitSensorRadius(lua_State* L)
 {
@@ -5377,7 +5377,7 @@ int LuaSyncedCtrl::SetFeaturePieceVisible(lua_State* L)
  * @param featureID integer
  * @param pieceIndex number
  * @param matrix number[] an array of 16 floats
- * @return boolean? valid - if the matrix can be used for the purpose of defining the piece spatial transformation
+ * @return boolean? valid whether the matrix can be used for the purpose of defining the piece spatial transformation
  */
 int LuaSyncedCtrl::SetFeaturePieceMatrix(lua_State* L)
 {
@@ -7031,7 +7031,7 @@ int LuaSyncedCtrl::AddSmoothMesh(lua_State* L)
  * @param z number
  * @param height number
  * @param terraform number? (Default: `1`)
- * @return number? The absolute height difference, or `nil` if coordinates are invalid.
+ * @return number? heightDifference The absolute height difference, or `nil` if coordinates are invalid.
  */
 int LuaSyncedCtrl::SetSmoothMesh(lua_State* L)
 {