Fix #1647, add some docs to Lua API

rts/Lua/LuaSyncedRead.cpp

@@ -4666,10 +4666,17 @@ int LuaSyncedRead::GetUnitCurrentBuildPower(lua_State* L)
 }
 
 
-/***
+/*** Get a unit's carried resources
  *
  * @function Spring.GetUnitHarvestStorage
+ *
+ * Checks resources being carried internally by the unit.
+ *
  * @number unitID
+ * @treturn number storedMetal
+ * @treturn number maxStoredMetal
+ * @treturn number storedEnergy
+ * @treturn number maxStoredEnergy
  */
 int LuaSyncedRead::GetUnitHarvestStorage(lua_State* L)
 {
@@ -4717,10 +4724,15 @@ int LuaSyncedRead::GetUnitBuildParams(lua_State* L)
 	return 0;
 }
 
-/***
+/*** Is builder in build stance
  *
  * @function Spring.GetUnitInBuildStance
+ *
+ * Checks if a builder is in build stance, i.e. can create nanoframes.
+ * Returns nil for non-builders.
+ *
  * @number unitID
+ * @treturn bool inBuildStance
  */
 int LuaSyncedRead::GetUnitInBuildStance(lua_State* L)
 {
@@ -4738,10 +4750,19 @@ int LuaSyncedRead::GetUnitInBuildStance(lua_State* L)
 	return 1;
 }
 
-/***
+/*** Get construction FX attachment points
  *
  * @function Spring.GetUnitNanoPieces
+ *
+ * Returns an array of pieces which represent construction
+ * points. Default engine construction FX (nano spray) will
+ * originate there.
+ *
+ * Only works on builders and factories, returns nil (NOT empty table)
+ * for other units.
+ *
  * @number unitID
+ * @return pieceArray {pieceID, pieceID, ...}
  */
 int LuaSyncedRead::GetUnitNanoPieces(lua_State* L)
 {
@@ -4784,10 +4805,15 @@ int LuaSyncedRead::GetUnitNanoPieces(lua_State* L)
 }
 
 
-/***
+/*** Get the transport carrying the unit
  *
  * @function Spring.GetUnitTransporter
+ *
+ * Returns the unit ID of the transport, if any.
+ * Returns nil if the unit is not being transported.
+ *
  * @number unitID
+ * @treturn number|nil transportUnitID
  */
 int LuaSyncedRead::GetUnitTransporter(lua_State* L)
 {
@@ -4803,10 +4829,15 @@ int LuaSyncedRead::GetUnitTransporter(lua_State* L)
 }
 
 
-/***
+/*** Get units being transported
  *
  * @function Spring.GetUnitIsTransporting
+ *
+ * Returns an array of unitIDs being transported by this unit.
+ * Returns nil (NOT an empty array) for units that are not transports.
+ *
  * @number unitID
+ * @return transporteeArray {unitID, unitID, ...}
  */
 int LuaSyncedRead::GetUnitIsTransporting(lua_State* L)
 {
@@ -4833,6 +4864,9 @@ int LuaSyncedRead::GetUnitIsTransporting(lua_State* L)
  *
  * @function Spring.GetUnitShieldState
  * @number unitID
+ * @number[opt] weaponNum Optional if the unit has just one shield
+ * @treturn number isEnabled Warning, number not bool. 0 or 1
+ * @treturn number currentPower
  */
 int LuaSyncedRead::GetUnitShieldState(lua_State* L)
 {
@@ -4917,10 +4951,16 @@ int LuaSyncedRead::GetUnitFlanking(lua_State* L)
 }
 
 
-/***
+/*** Get a unit's engagement range
  *
  * @function Spring.GetUnitMaxRange
+ *
+ * Returns the range at which a unit will stop to engage.
+ * By default this is the highest among the unit's weapon ranges (hence name),
+ * but can be changed dynamically. Also note that unarmed units ignore this.
+ *
  * @number unitID
+ * @treturn number maxRange
  */
 int LuaSyncedRead::GetUnitMaxRange(lua_State* L)
 {
@@ -4940,10 +4980,36 @@ int LuaSyncedRead::GetUnitMaxRange(lua_State* L)
 ******************************************************************************/
 
 
-/***
+/*** Check the state of a unit's weapon
  *
  * @function Spring.GetUnitWeaponState
+ *
+ * Available states to poll:
+ *   "reloadFrame" (frame on which the weapon will be ready to fire),
+ *   "reloadSpeed" (reload time in seconds),
+ *   "range" (in elmos),
+ *   "autoTargetRangeBoost" (predictive aiming range buffer, in elmos),
+ *   "projectileSpeed" (in elmos/frame),
+ *   "reloadTimeXP" (reload time after XP bonus, in seconds),
+ *   "reaimTime" (frames between AimWeapon calls),
+ *   "burst" (shots in a burst),
+ *   "burstRate" (delay between shots in a burst, in seconds),
+ *   "projectiles" (projectiles per shot),
+ *   "salvoLeft" (shots remaining in ongoing burst),
+ *   "nextSalvo" (simframe of the next shot in an ongoing burst),
+ *   "accuracy" (INaccuracy after XP bonus),
+ *   "sprayAngle" (spray angle after XP bonus),
+ *   "targetMoveError" (extra inaccuracy against moving targets, after XP bonus)
+ *   "avoidFlags" (bitmask for targeting avoidance),
+ *   "collisionFlags" (bitmask for collisions).
+ *
+ * The state "salvoError" is an exception and returns a table: {x, y, z},
+ * which represents the inaccuracy error of the ongoing burst.
+ *
  * @number unitID
+ * @number weaponNum
+ * @string stateName
+ * @return number stateValue
  */
 int LuaSyncedRead::GetUnitWeaponState(lua_State* L)
 {