diff --git a/rts/Lua/LuaHandle.cpp b/rts/Lua/LuaHandle.cpp
index 195d7aa7a3..6eb9ef55f5 100644
--- a/rts/Lua/LuaHandle.cpp
+++ b/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)
 {
diff --git a/rts/Lua/LuaHandleSynced.cpp b/rts/Lua/LuaHandleSynced.cpp
index 9ae6a0fe2b..9aadd8a928 100644
--- a/rts/Lua/LuaHandleSynced.cpp
+++ b/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
  */
diff --git a/rts/Lua/LuaMathExtra.cpp b/rts/Lua/LuaMathExtra.cpp
index 544a6298b4..ef203b2726 100644
--- a/rts/Lua/LuaMathExtra.cpp
+++ b/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;
diff --git a/rts/Lua/LuaOpenGL.cpp b/rts/Lua/LuaOpenGL.cpp
index a01bb05519..3c3f2e424f 100644
--- a/rts/Lua/LuaOpenGL.cpp
+++ b/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)
 {
diff --git a/rts/Lua/LuaSyncedCtrl.cpp b/rts/Lua/LuaSyncedCtrl.cpp
index fe7eeea65e..e89cad8756 100644
--- a/rts/Lua/LuaSyncedCtrl.cpp
+++ b/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)
 {
diff --git a/rts/Lua/LuaSyncedRead.cpp b/rts/Lua/LuaSyncedRead.cpp
index 65c2cd1040..ae8a5c5b34 100644
--- a/rts/Lua/LuaSyncedRead.cpp
+++ b/rts/Lua/LuaSyncedRead.cpp
@@ -1607,7 +1607,7 @@ int LuaSyncedRead::GetTeamStartPosition(lua_State* L)
 /***
  *
  * @function Spring.GetMapStartPositions
- * @return float3[] array of positions indexed by teamID
+ * @return float3[] startPositions array of positions indexed by teamID
  */
 int LuaSyncedRead::GetMapStartPositions(lua_State* L)
 {
@@ -1702,7 +1702,7 @@ int LuaSyncedRead::GetTeamList(lua_State* L)
  * @function Spring.GetPlayerList
  * @param teamID integer? (Default: `-1`) to filter by when >= 0
  * @param active boolean? (Default: `false`) whether to filter only active teams
- * @return number[]? list of playerIDs
+ * @return number[]? playerIDs List of playerIDs.
  */
 int LuaSyncedRead::GetPlayerList(lua_State* L)
 {
@@ -2034,7 +2034,7 @@ int LuaSyncedRead::GetTeamDamageStats(lua_State* L)
  * @param teamID integer
  * @param startIndex integer
  * @param endIndex integer? (Default: startIndex)
- * @return TeamStats[] The team stats history, or `nil` if unable to resolve team.
+ * @return TeamStats[] teamStatsHistory The team stats history, or `nil` if unable to resolve team.
  */
 int LuaSyncedRead::GetTeamStatsHistory(lua_State* L)
 {
@@ -4264,8 +4264,8 @@ int LuaSyncedRead::GetUnitResources(lua_State* L)
 /***
  * @function Spring.GetUnitStorage
  * @param unitID integer
- * @return number Unit's metal storage
- * @return number Unit's energy storage
+ * @return number metalStorage Unit's metal storage
+ * @return number energyStorage Unit's energy storage
  */
 int LuaSyncedRead::GetUnitStorage(lua_State* L)
 {
@@ -6356,7 +6356,7 @@ int LuaSyncedRead::GetUnitCurrentCommand(lua_State* L)
  *
  * @param unitID integer
  * @param count 0 Returns the number of commands in the units queue.
- * @return integer The number of commands in the unit queue.
+ * @return integer cmdCount The number of commands in the unit queue.
  */
 int LuaSyncedRead::GetUnitCommands(lua_State* L)
 {
@@ -6404,7 +6404,7 @@ int LuaSyncedRead::GetUnitCommands(lua_State* L)
  *
  * @param unitID integer
  * @param count 0 Returns the number of commands in the factory queue.
- * @return integer The number of commands in the factory queue.
+ * @return integer cmdCount The number of commands in the factory queue.
  *
  * @see Spring.GetFactoryCommandCount for replacement function.
  */
@@ -6441,7 +6441,7 @@ int LuaSyncedRead::GetFactoryCommands(lua_State* L)
  *
  * @function Spring.GetUnitCommandCount
  * @param unitID integer
- * @return integer The number of commands in the unit's queue.
+ * @return integer cmdCount The number of commands in the unit's queue.
  */
 int LuaSyncedRead::GetUnitCommandCount(lua_State* L)
 {
@@ -6464,7 +6464,7 @@ int LuaSyncedRead::GetUnitCommandCount(lua_State* L)
  *
  * @function Spring.GetFactoryCommandCount
  * @param unitID integer
- * @return integer The number of commands in the factory queue.
+ * @return integer cmdCount The number of commands in the factory queue.
  *
  * @see Spring.GetFactoryCommands to get the factory commands.
  * @see Spring.GetFactoryCounts to get command counts grouped by cmdID.
@@ -7197,8 +7197,8 @@ int LuaSyncedRead::GetFeatureResurrect(lua_State* L)
  *
  * @function Spring.GetFeatureLastAttackedPiece
  * @param featureID integer
- * @return string|""|nil Last hit piece name
- * @return integer? frame it was last hit on, nil when featureID is not valid
+ * @return string|""|nil pieceName Last hit piece name
+ * @return integer? frame frame it was last hit on, nil when featureID is not valid
  */
 int LuaSyncedRead::GetFeatureLastAttackedPiece(lua_State* L)
 {
@@ -9093,7 +9093,7 @@ int LuaSyncedRead::GetUnitScriptPiece(lua_State* L)
  *
  * @param unitID integer
  *
- * @return table<string,number> where keys are piece names and values are piece indices
+ * @return table<string,number> pieceInfos where keys are piece names and values are piece indices
  */
 int LuaSyncedRead::GetUnitScriptNames(lua_State* L)
 {
diff --git a/rts/Lua/LuaUnsyncedCtrl.cpp b/rts/Lua/LuaUnsyncedCtrl.cpp
index d140eab26f..ab93fd59bd 100644
--- a/rts/Lua/LuaUnsyncedCtrl.cpp
+++ b/rts/Lua/LuaUnsyncedCtrl.cpp
@@ -5558,7 +5558,7 @@ int LuaUnsyncedCtrl::SetClipboard(lua_State* L)
  *   wantYield = wantYield and Spring.Yield()
  * end
  *
- * @return boolean when true caller should continue calling `Spring.Yield` during the widgets/gadgets load, when false it shouldn't call it any longer.
+ * @return boolean continueYielding when true caller should continue calling `Spring.Yield` during the widgets/gadgets load, when false it shouldn't call it any longer.
  */
 int LuaUnsyncedCtrl::Yield(lua_State* L)
 {
diff --git a/rts/Lua/LuaUnsyncedRead.cpp b/rts/Lua/LuaUnsyncedRead.cpp
index 91919e111e..f48907032c 100644
--- a/rts/Lua/LuaUnsyncedRead.cpp
+++ b/rts/Lua/LuaUnsyncedRead.cpp
@@ -1055,7 +1055,7 @@ int LuaUnsyncedRead::GetMiniMapGeometry(lua_State* L)
 /*** Get minimap rotation
  *
  * @function Spring.GetMiniMapRotation
- * @return number amount in radians
+ * @return number rotation in radians
  */
 int LuaUnsyncedRead::GetMiniMapRotation(lua_State* L)
 {
@@ -1205,7 +1205,7 @@ int LuaUnsyncedRead::GetFrameTimeOffset(lua_State* L)
  *
  * Returns the game time, taking the interpolated draw frame into account.
  *
- * @return number game time in seconds
+ * @return number time in seconds
  */
 int LuaUnsyncedRead::GetGameSecondsInterpolated(lua_State* L)
 {
@@ -1331,7 +1331,7 @@ int LuaUnsyncedRead::GetUnitLuaDraw(lua_State* L)
  *
  * @function Spring.GetUnitNoDraw
  * @param unitID integer
- * @return boolean? nil when unitID cannot be parsed
+ * @return boolean? enabled nil when unitID cannot be parsed
  */
 int LuaUnsyncedRead::GetUnitNoDraw(lua_State* L)
 {
@@ -1342,7 +1342,7 @@ int LuaUnsyncedRead::GetUnitNoDraw(lua_State* L)
  *
  * @function Spring.GetUnitEngineDrawMask
  * @param unitID integer
- * @return boolean? nil when unitID cannot be parsed
+ * @return boolean? drawMask nil when unitID cannot be parsed
  */
 int LuaUnsyncedRead::GetUnitEngineDrawMask(lua_State* L)
 {
@@ -1353,7 +1353,7 @@ int LuaUnsyncedRead::GetUnitEngineDrawMask(lua_State* L)
  *
  * @function Spring.GetUnitAlwaysUpdateMatrix
  * @param unitID integer
- * @return boolean? nil when unitID cannot be parsed
+ * @return boolean? alwaysUpdateMatrix nil when unitID cannot be parsed
  */
 int LuaUnsyncedRead::GetUnitAlwaysUpdateMatrix(lua_State* L)
 {
@@ -1370,7 +1370,7 @@ int LuaUnsyncedRead::GetUnitAlwaysUpdateMatrix(lua_State* L)
  *
  * @function Spring.GetUnitDrawFlag
  * @param unitID integer
- * @return number? nil when unitID cannot be parsed
+ * @return number? drawFlag nil when unitID cannot be parsed
  */
 int LuaUnsyncedRead::GetUnitDrawFlag(lua_State* L)
 {
@@ -1387,7 +1387,7 @@ int LuaUnsyncedRead::GetUnitDrawFlag(lua_State* L)
  *
  * @function Spring.GetUnitNoMinimap
  * @param unitID integer
- * @return boolean? nil when unitID cannot be parsed
+ * @return boolean? noMinimap nil when unitID cannot be parsed
  */
 int LuaUnsyncedRead::GetUnitNoMinimap(lua_State* L)
 {
@@ -1651,7 +1651,7 @@ int LuaUnsyncedRead::GetUnitSelectionVolumeData(lua_State* L)
  *
  * @function Spring.GetFeatureLuaDraw
  * @param featureID integer
- * @return boolean? nil when featureID cannot be parsed
+ * @return boolean? luaDraw nil when featureID cannot be parsed
  */
 int LuaUnsyncedRead::GetFeatureLuaDraw(lua_State* L)
 {
@@ -1662,7 +1662,7 @@ int LuaUnsyncedRead::GetFeatureLuaDraw(lua_State* L)
  *
  * @function Spring.GetFeatureNoDraw
  * @param featureID integer
- * @return boolean? nil when featureID cannot be parsed
+ * @return boolean? noDraw nil when featureID cannot be parsed
  */
 int LuaUnsyncedRead::GetFeatureNoDraw(lua_State* L)
 {
@@ -1673,7 +1673,7 @@ int LuaUnsyncedRead::GetFeatureNoDraw(lua_State* L)
  *
  * @function Spring.GetFeatureEngineDrawMask
  * @param featureID integer
- * @return boolean? nil when featureID cannot be parsed
+ * @return boolean? drawMask nil when featureID cannot be parsed
  */
 int LuaUnsyncedRead::GetFeatureEngineDrawMask(lua_State* L)
 {
@@ -1684,7 +1684,7 @@ int LuaUnsyncedRead::GetFeatureEngineDrawMask(lua_State* L)
  *
  * @function Spring.GetFeatureAlwaysUpdateMatrix
  * @param featureID integer
- * @return boolean? nil when featureID cannot be parsed
+ * @return boolean? alwaysUpdateMatrix nil when featureID cannot be parsed
  */
 int LuaUnsyncedRead::GetFeatureAlwaysUpdateMatrix(lua_State* L)
 {
@@ -1701,7 +1701,7 @@ int LuaUnsyncedRead::GetFeatureAlwaysUpdateMatrix(lua_State* L)
  *
  * @function Spring.GetFeatureDrawFlag
  * @param featureID integer
- * @return number? nil when featureID cannot be parsed
+ * @return number? drawFlag nil when featureID cannot be parsed
  */
 int LuaUnsyncedRead::GetFeatureDrawFlag(lua_State* L)
 {
@@ -1767,7 +1767,13 @@ static int GetObjectTransformMatrix(const CSolidObject* o, lua_State* L)
  *
  * @function Spring.GetUnitTransformMatrix
  * @param unitID integer
- * @return number? m11 nil when unitID cannot be parsed
+ * @return nil # when unitID cannot be parsed
+ */
+/***
+ *
+ * @function Spring.GetUnitTransformMatrix
+ * @param unitID integer
+ * @return number m11
  * @return number m12
  * @return number m13
  * @return number m14
@@ -1791,7 +1797,13 @@ int LuaUnsyncedRead::GetUnitTransformMatrix(lua_State* L) { return (GetObjectTra
  *
  * @function Spring.GetFeatureTransformMatrix
  * @param featureID integer
- * @return number? m11 nil when featureID cannot be parsed
+ * @return nil # when featureID cannot be parsed
+ */
+ /***
+ *
+ * @function Spring.GetFeatureTransformMatrix
+ * @param featureID integer
+ * @return number m11
  * @return number m12
  * @return number m13
  * @return number m14
@@ -2703,8 +2715,8 @@ int LuaUnsyncedRead::GetSelectedUnits(lua_State* L)
 /*** Get selected units aggregated by unitDefID
  *
  * @function Spring.GetSelectedUnitsSorted
- * @return table<number,number[]> where keys are unitDefIDs and values are unitIDs
- * @return integer the number of unitDefIDs
+ * @return table<number,number[]> unitsIDs where keys are unitDefIDs and values are unitIDs
+ * @return integer count the number of unitDefIDs
  */
 int LuaUnsyncedRead::GetSelectedUnitsSorted(lua_State* L)
 {
@@ -2720,7 +2732,7 @@ int LuaUnsyncedRead::GetSelectedUnitsSorted(lua_State* L)
  * @function Spring.GetSelectedUnitsCounts
  *
  * @return table<number,number> unitsCounts where keys are unitDefIDs and values are counts
- * @return integer the number of unitDefIDs
+ * @return integer count the number of unitDefIDs
  */
 int LuaUnsyncedRead::GetSelectedUnitsCounts(lua_State* L)
 {
@@ -2852,7 +2864,7 @@ int LuaUnsyncedRead::GetMapDrawMode(lua_State* L)
  * @param lodMin number
  * @param luaTexName string
  * @param lodMax number? (Default: lodMin)
- * @return boolean? success
+ * @return boolean? squareTexture
  */
 int LuaUnsyncedRead::GetMapSquareTexture(lua_State* L)
 {
@@ -4189,7 +4201,7 @@ int LuaUnsyncedRead::GetModKeyState(lua_State* L)
 /***
  *
  * @function Spring.GetPressedKeys
- * @return table<number|string,true> where keys are keyCodes or key names
+ * @return table<number|string,true> keys where keys are keyCodes or key names
  */
 int LuaUnsyncedRead::GetPressedKeys(lua_State* L)
 {
@@ -4220,7 +4232,7 @@ int LuaUnsyncedRead::GetPressedKeys(lua_State* L)
 /***
  *
  * @function Spring.GetPressedScans
- * @return table<number|string,true> where keys are scanCodes or scan names
+ * @return table<number|string,true> scans where keys are scanCodes or scan names
  */
 int LuaUnsyncedRead::GetPressedScans(lua_State* L)
 {
@@ -4400,7 +4412,7 @@ int LuaUnsyncedRead::GetActionHotKeys(lua_State* L)
 /***
  *
  * @function Spring.GetGroupList
- * @return table<number,number>? where keys are groupIDs and values are counts
+ * @return table<number,number>? groupCounts where keys are groupIDs and values are counts
  */
 int LuaUnsyncedRead::GetGroupList(lua_State* L)
 {
@@ -4493,7 +4505,7 @@ int LuaUnsyncedRead::GetGroupUnits(lua_State* L)
  *
  * @function Spring.GetGroupUnitsSorted
  * @param groupID integer
- * @return table<number,number[]>? where keys are unitDefIDs and values are unitIDs
+ * @return table<number,number[]>? unitsIDs where keys are unitDefIDs and values are unitIDs
  */
 int LuaUnsyncedRead::GetGroupUnitsSorted(lua_State* L)
 {
@@ -4510,7 +4522,7 @@ int LuaUnsyncedRead::GetGroupUnitsSorted(lua_State* L)
  *
  * @function Spring.GetGroupUnitsCounts
  * @param groupID integer
- * @return table<number,number>? where keys are unitDefIDs and values are counts
+ * @return table<number,number>? unitsCounts where keys are unitDefIDs and values are counts
  */
 int LuaUnsyncedRead::GetGroupUnitsCounts(lua_State* L)
 {
@@ -4984,7 +4996,7 @@ int LuaUnsyncedRead::GetGroundDecalSizeAndHeight(lua_State* L)
  *
  * @function Spring.GetGroundDecalRotation
  * @param decalID integer
- * @return number? rotation Rotation in radians.
+ * @return number? rotation in radians
  */
 int LuaUnsyncedRead::GetGroundDecalRotation(lua_State* L)
 {
diff --git a/rts/Lua/LuaVBOImpl.cpp b/rts/Lua/LuaVBOImpl.cpp
index 91b936303c..6cc66df568 100644
--- a/rts/Lua/LuaVBOImpl.cpp
+++ b/rts/Lua/LuaVBOImpl.cpp
@@ -1176,7 +1176,7 @@ size_t LuaVBOImpl::UploadImpl(const std::vector<TIn>& dataVec, uint32_t elemOffs
  *
  * Also fills in VBO definition data as they're set for engine models (no need to do VBO:Define()).
  *
- * @return nil|number buffer size in bytes
+ * @return nil|number size buffer size in bytes
  */
 size_t LuaVBOImpl::ModelsVBO()
 {
@@ -1340,7 +1340,7 @@ size_t LuaVBOImpl::InstanceDataFromFeatureIDs(const sol::stack_table& ids, int a
  * @param attrID integer
  * @param teamIdOpt integer?
  * @param elementOffset integer?
- * @return number[] matDataVec 4x4 matrix
+ * @return number[][] matDataVec 4x4 matrix
  * @return integer elemOffset
  * @return integer|[integer,integer,integer,integer] attrID
  */