[pull] master from beyond-all-reason:master

rts/Lua/LuaHandle.cpp

@@ -705,11 +705,6 @@ bool CLuaHandle::HasCallIn(lua_State* L, const string& name) const
 	return found;
 }
 
-
-/***
- * @function Script.UpdateCallin
- * @param name string
- */
 bool CLuaHandle::UpdateCallIn(lua_State* L, const string& name)
 {
 	RECOIL_DETAILED_TRACY_ZONE;
@@ -1036,7 +1031,7 @@ void CLuaHandle::PlayerAdded(int playerID)
  *
  * @function Callins:PlayerRemoved
  * @param playerID integer
- * @param reason string
+ * @param reason integer
  */
 void CLuaHandle::PlayerRemoved(int playerID, int reason)
 {
@@ -3165,9 +3160,9 @@ bool CLuaHandle::KeyMapChanged()
  * @class KeyModifiers
  * @x_helper
  *
- * @field right boolean Right mouse key pressed
  * @field alt boolean Alt key pressed
  * @field ctrl boolean Ctrl key pressed
+ * @field meta boolean Meta/GUI key pressed
  * @field shift boolean Shift key pressed
  */
 
@@ -3181,10 +3176,10 @@ bool CLuaHandle::KeyMapChanged()
  * @param keyCode number
  * @param mods KeyModifiers
  * @param isRepeat boolean If you want an action to occur only once check for isRepeat == false.
- * @param label boolean the name of the key
+ * @param label string the name of the key
  * @param utf32char number (deprecated) always 0
  * @param scanCode number
- * @param actionList table the list of actions for this keypress
+ * @param actionList table? the list of actions for this keypress, when available
  * @return boolean halt whether to halt the chain for consumers of the keypress
  */
 bool CLuaHandle::KeyPress(int keyCode, int scanCode, bool isRepeat)
@@ -3246,10 +3241,10 @@ bool CLuaHandle::KeyPress(int keyCode, int scanCode, bool isRepeat)
  *
  * @param keyCode number
  * @param mods KeyModifiers
- * @param label boolean the name of the key
+ * @param label string the name of the key
  * @param utf32char number (deprecated) always 0
  * @param scanCode number
- * @param actionList table the list of actions for this keyrelease
+ * @param actionList table? the list of actions for this keyrelease, when available
  *
  * @return boolean
  */
@@ -3642,6 +3637,7 @@ void CLuaHandle::MiniMapRotationChanged(const float newRot, const float oldRot)
  * @function Callins:MiniMapStateChanged
  * @param isMinimized boolean
  * @param isMaximized boolean
+ * @param isSlaved boolean
  */
 void CLuaHandle::MiniMapStateChanged(const bool isMinimized,
 									const bool isMaximized,
@@ -4465,6 +4461,11 @@ int CLuaHandle::CallOutGetCallInList(lua_State* L)
 }
 
 
+/***
+ * @function Script.UpdateCallIn
+ * @param name string
+ * @return nil
+ */
 int CLuaHandle::CallOutUpdateCallIn(lua_State* L)
 {
 

rts/Lua/LuaHandleSynced.cpp

@@ -281,7 +281,7 @@ bool CUnsyncedLuaHandle::DrawFeature(const CFeature* feature)
 /*** For custom rendering of shields.
  *
  * @function UnsyncedCallins:DrawShield
- * @param featureID integer
+ * @param unitID integer
  * @param weaponID integer
  * @param drawMode number
  * @return boolean suppressEngineDraw
@@ -978,7 +978,7 @@ bool CSyncedLuaHandle::AllowUnitCloak(const CUnit* unit, const CUnit* enemy)
 
 /***
  *
- * @function SyncedCallins:AllowUnitCloak
+ * @function SyncedCallins:AllowUnitDecloak
  * @param unitID integer
  * @param objectID integer?
  * @param weaponNum number?

rts/Lua/LuaOpenGL.cpp

@@ -2109,7 +2109,7 @@ int LuaOpenGL::DrawGroundCircle(lua_State* L)
 
 
 /***
- * @function gl.DrawGroundCircle
+ * @function gl.DrawGroundQuad
  * @param x0 number
  * @param z0 number
  * @param x1 number
@@ -2118,7 +2118,7 @@ int LuaOpenGL::DrawGroundCircle(lua_State* L)
  * @param useTxcd boolean? (Default: `false`)
  */
 /***
- * @function gl.DrawGroundCircle
+ * @function gl.DrawGroundQuad
  * @param x0 number
  * @param z0 number
  * @param x1 number
@@ -2825,7 +2825,7 @@ int LuaOpenGL::Rect(lua_State* L)
 
 
 /***
- * @function gl.Rect
+ * @function gl.TexRect
  * @param x1 number
  * @param y1 number
  * @param x2 number
@@ -2834,7 +2834,7 @@ int LuaOpenGL::Rect(lua_State* L)
  * @param flipTCoords boolean?
  */
 /***
- * @function gl.Rect
+ * @function gl.TexRect
  * @param x1 number
  * @param y1 number
  * @param x2 number
@@ -4490,13 +4490,13 @@ int LuaOpenGL::ActiveTexture(lua_State* L)
 
 
 /***
- * @function gl.TextEnv
+ * @function gl.TexEnv
  * @param target GL
  * @param pname GL
  * @param value number
  */
 /***
- * @function gl.TextEnv
+ * @function gl.TexEnv
  * @param target GL
  * @param pname GL
  * @param r number? (Default: `0.0`)

rts/Lua/LuaPathFinder.cpp

@@ -264,9 +264,9 @@ int LuaPathFinder::RequestPath(lua_State* L)
 
 /***
  * @function Spring.InitPathNodeCostsArray
- * @param overlayIndex number
- * @param sizeX number
- * @param sizeZ number
+ * @param overlayIndex integer
+ * @param sizeX integer
+ * @param sizeZ integer
  * @return boolean success
  */
 int LuaPathFinder::InitPathNodeCostsArray(lua_State* L)
@@ -406,9 +406,8 @@ int LuaPathFinder::GetPathNodeCosts(lua_State* L)
 
 /***
  * @function Spring.SetPathNodeCost
- * @param overlayIndex number
- * @param nodeX number
- * @param nodeZ number
+ * @param overlayIndex integer
+ * @param costIndex integer 0-based index in the overlay
  * @param cost number
  * @return boolean success
  */
@@ -444,8 +443,8 @@ int LuaPathFinder::SetPathNodeCost(lua_State* L)
 
 /***
  * @function Spring.GetPathNodeCost
- * @param nodeX number
- * @param nodeZ number
+ * @param nodeX integer Heightmap node X coordinate
+ * @param nodeZ integer Heightmap node Z coordinate
  * @return number cost
  */
 int LuaPathFinder::GetPathNodeCost(lua_State* L)

rts/Lua/LuaRules.cpp

@@ -117,6 +117,11 @@ bool CLuaRules::AddUnsyncedCode(lua_State* L)
 // LuaRules Call-Outs
 //
 
+/***
+ *
+ * @function Script.PermitHelperAIs
+ * @param permit boolean
+ */
 int CLuaRules::PermitHelperAIs(lua_State* L)
 {
 	if (!lua_isboolean(L, 1)) {

rts/Lua/LuaShaders.cpp

@@ -990,6 +990,17 @@ int LuaShaders::GetUniformLocation(lua_State* L)
 	return 1;
 }
 
+/***
+ * Returns the subroutine index for a shader program.
+ *
+ * @function gl.GetSubroutineIndex
+ * @param shaderID integer
+ * @param shaderType integer
+ * @param name string
+ * @return integer? index
+ *
+ * Returns no value when shader support is unavailable or `shaderID` is invalid.
+ */
 int LuaShaders::GetSubroutineIndex(lua_State* L)
 {
 	if (!IS_GL_FUNCTION_AVAILABLE(glGetSubroutineIndex))
@@ -1038,7 +1049,25 @@ namespace {
 	}
 }
 
+/***
+ * Writes user-defined model uniforms for a unit.
+ *
+ * @function gl.SetUnitBufferUniforms
+ * @param unitID integer
+ * @param values number[]
+ * @param offset integer?
+ * @return integer count
+ */
 int LuaShaders::SetUnitBufferUniforms(lua_State* L) { return SetObjectBufferUniforms<CUnit>(L, __func__); }
+/***
+ * Writes user-defined model uniforms for a feature.
+ *
+ * @function gl.SetFeatureBufferUniforms
+ * @param featureID integer
+ * @param values number[]
+ * @param offset integer?
+ * @return integer count
+ */
 int LuaShaders::SetFeatureBufferUniforms(lua_State* L) { return SetObjectBufferUniforms<CFeature>(L, __func__); }
 
 
@@ -1292,6 +1321,13 @@ int LuaShaders::UniformMatrix(lua_State* L)
 	return 0;
 }
 
+/***
+ * Selects a subroutine for the active shader program.
+ *
+ * @function gl.UniformSubroutine
+ * @param shaderType integer
+ * @param index integer
+ */
 int LuaShaders::UniformSubroutine(lua_State* L)
 {
 	if (!IS_GL_FUNCTION_AVAILABLE(glUniformSubroutinesuiv))

rts/Lua/LuaSyncedRead.cpp

@@ -4835,6 +4835,11 @@ int LuaSyncedRead::GetUnitHarvestStorage(lua_State* L)
  *
  * @function Spring.GetUnitBuildParams
  * @param unitID integer
+ * @param paramName string One of `buildRange`, `buildDistance`, or `buildRange3D`.
+ * @return number|boolean|nil value
+ *
+ * Returns no value when the unit is not an allied builder or when `paramName`
+ * is not recognized.
  */
 int LuaSyncedRead::GetUnitBuildParams(lua_State* L)
 {
@@ -5887,6 +5892,25 @@ int LuaSyncedRead::GetUnitCollisionVolumeData(lua_State* L)
 	return LuaUtils::PushColVolData(L, &unit->collisionVolume);
 }
 
+/***
+ *
+ * @function Spring.GetUnitPieceCollisionVolumeData
+ * @param unitID integer
+ * @param pieceIndex integer 1-based local-model piece index
+ * @return number? scaleX
+ * @return number? scaleY
+ * @return number? scaleZ
+ * @return number? offsetX
+ * @return number? offsetY
+ * @return number? offsetZ
+ * @return integer? volumeType
+ * @return integer? testType
+ * @return integer? primaryAxis
+ * @return boolean? disabled
+ *
+ * Returns no values when `unitID` is invalid or not in line of sight, or when
+ * `pieceIndex` is invalid.
+ */
 int LuaSyncedRead::GetUnitPieceCollisionVolumeData(lua_State* L)
 {
 	return (PushPieceCollisionVolumeData(L, ParseInLosUnit(L, __func__, 1)));
@@ -9279,11 +9303,12 @@ static int TraceRayGroundImpl(lua_State *const L, const float3 &pos, const float
  * @param dirX number
  * @param dirY number
  * @param dirZ number
+ * @param maxLength number? (Default: `999999`)
  * @param testWater boolean? (Default: `true`)
- * @return number rayLength
- * @return number posX
- * @return number posY
- * @return number posZ
+ * @return number? rayLength
+ * @return number? posX
+ * @return number? posY
+ * @return number? posZ
  */
 int LuaSyncedRead::TraceRayGroundInDirection(lua_State* L)
 {

rts/Lua/LuaUnsyncedRead.cpp

@@ -1202,6 +1202,8 @@ int LuaUnsyncedRead::GetFrameTimeOffset(lua_State* L)
 }
 
 /*** Gets game time for drawing purposes
+ *
+ * @function Spring.GetGameSecondsInterpolated
  *
  * Returns the game time, taking the interpolated draw frame into account.
  *

rts/Lua/LuaVFS.cpp

@@ -1084,15 +1084,15 @@ int LuaVFS::PackS32(lua_State* L) { return PackType<std::int32_t>(L); }
 
 /***
  * Convert signed 32-bit float(s) to binary string.
- * @function VFS.PackS32 
- * @param ... integer Numbers to pack.
- * @return string
+ * @function VFS.PackF32
+ * @param ... number Numbers to pack.
+ * @return string?
  */
 /***
  * Convert signed 32-bit float(s) to binary string.
- * @function VFS.PackS32 
- * @param numbers integer[] Numbers to pack.
- * @return string
+ * @function VFS.PackF32
+ * @param numbers number[] Numbers to pack.
+ * @return string?
  */
 int LuaVFS::PackF32(lua_State* L) { return PackType<float>(L); }
 

rts/Lua/LuaVFSDownload.cpp

@@ -312,6 +312,12 @@ bool LuaVFSDownload::PushEntries(lua_State* L)
 	return true;
 }
 
+/***
+ * Queue an archive download through pr-downloader.
+ * @function VFS.DownloadArchive
+ * @param filename string Archive or rapid package name.
+ * @param category string One of `map`, `game`, or `engine`.
+ */
 int LuaVFSDownload::DownloadArchive(lua_State* L)
 {
 	const std::string& filename = luaL_checkstring(L, 1);
@@ -337,12 +343,22 @@ int LuaVFSDownload::DownloadArchive(lua_State* L)
 	return 0;
 }
 
+/***
+ * Abort a queued or active archive download.
+ * @function VFS.AbortDownload
+ * @param id integer Download queue identifier.
+ * @return boolean removed Whether a matching queued or active download was removed.
+ */
 int LuaVFSDownload::AbortDownload(lua_State* L)
 {
 	lua_pushboolean(L, downloadQueue.Remove(luaL_checkint(L, 1)));
 	return 1;
 }
 
+/***
+ * Rescan all data directories for newly added archives.
+ * @function VFS.ScanAllDirs
+ */
 int LuaVFSDownload::ScanAllDirs(lua_State* L)
 {
 	archiveScanner->ScanAllDirs();

rts/Rml/SolLua/bind/Element.cpp

@@ -473,7 +473,7 @@ namespace Rml::SolLua
 			/***
 			 * Is a screen-space point within this element?
 			 * @function RmlUi.Element:IsPointWithinElement
-			 * @param point RmlUi.Vector2i
+			 * @param point RmlUi.Vector2f
 			 * @return boolean
 			 */
 			"IsPointWithinElement", &Rml::Element::IsPointWithinElement,