General documentation and code fixes (#1650)

Documentation updates for correctness and clarity.
General code formatting updates.
Ajustment to POSITIONABLE:GetCoord to make use of existing POINT:UpdateFromVec3.
Added comments about clarifying the difference between POSITIONABLE:GetCoordinate() and POSITIONABLE:GetCoord() and to perhaps consider a renaming or merging the functions with an optional flag.

Moose Development/Moose/Core/Point.lua

@@ -347,7 +347,6 @@ do -- COORDINATE
     return self
   end
 
-
   --- Returns the coordinate from the latitude and longitude given in decimal degrees.
   -- @param #COORDINATE self
   -- @param #number latitude Latitude in decimal degrees.
@@ -372,7 +371,6 @@ do -- COORDINATE
     return _coord
   end
 
-  
   --- Returns if the 2 coordinates are at the same 2D position.
   -- @param #COORDINATE self
   -- @param #COORDINATE Coordinate
@@ -551,7 +549,7 @@ do -- COORDINATE
   -- @param DCS#Distance Distance The Distance to be added in meters.
   -- @param DCS#Angle Angle The Angle in degrees. Defaults to 0 if not specified (nil).
   -- @param #boolean Keepalt If true, keep altitude of original coordinate. Default is that the new coordinate is created at the translated land height.
-  -- @param #boolean Overwrite If true, overwrite the original COORDINATE with the translated one. Otherwise, create a new COODINATE.
+  -- @param #boolean Overwrite If true, overwrite the original COORDINATE with the translated one. Otherwise, create a new COORDINATE.
   -- @return #COORDINATE The new calculated COORDINATE.
   function COORDINATE:Translate( Distance, Angle, Keepalt, Overwrite )
 
@@ -3004,7 +3002,6 @@ do -- POINT_VEC3
     return self
   end
 
-
   --- Create a new POINT_VEC3 object from  Vec3 coordinates.
   -- @param #POINT_VEC3 self
   -- @param DCS#Vec3 Vec3 The Vec3 point.
@@ -3017,8 +3014,6 @@ do -- POINT_VEC3
     return self
   end
 
-
-
   --- Return the x coordinate of the POINT_VEC3.
   -- @param #POINT_VEC3 self
   -- @return #number The x coodinate.

Moose Development/Moose/Functional/Range.lua

@@ -152,7 +152,7 @@
 --
 -- * The first parameter *targetnames* defines the target or targets. This can be a single item or a Table with the name(s) of @{Wrapper.Unit} or @{Static} objects defined in the mission editor.
 -- * The (optional) parameter *goodhitrange* specifies the radius in metres around the target within which a bomb/rocket hit is considered to be "good".
--- * If final (optional) parameter "*randommove*" can be enabled to create moving targets. If this parameter is set to true, the units of this bombing target will randomly move within the range zone.
+-- * If final (optional) parameter *randommove* can be enabled to create moving targets. If this parameter is set to true, the units of this bombing target will randomly move within the range zone.
 --   Note that there might be quirks since DCS units can get stuck in buildings etc. So it might be safer to manually define a route for the units in the mission editor if moving targets are desired.
 --
 -- ## Adding Groups
@@ -903,10 +903,10 @@ end
 
 --- Set player setting whether bomb impact points are smoked or not.
 -- @param #RANGE self
--- @param #boolean switch If true nor nil default is to smoke impact points of bombs.
+-- @param #boolean switch (Optional) If true, impact points of bombs will be smoked. Default is true.
 -- @return #RANGE self
 function RANGE:SetDefaultPlayerSmokeBomb(switch)
-  if switch==true or switch==nil then
+  if switch == nil or switch == true then
     self.defaultsmokebomb=true
   else
     self.defaultsmokebomb=false
@@ -1249,7 +1249,7 @@ end
 -- @param #number boxlength (Optional) Length of the approach box in meters. Default is 3000 m.
 -- @param #number boxwidth (Optional) Width of the approach box in meters. Default is 300 m.
 -- @param #number heading (Optional) Approach heading in Degrees. Default is heading of the unit as defined in the mission editor.
--- @param #boolean inverseheading (Optional) Take inverse heading (heading --> heading - 180 Degrees). Default is false.
+-- @param #boolean inverseheading (Optional) Use inverse heading (heading --> heading - 180 Degrees). Default is false.
 -- @param #number goodpass (Optional) Number of hits for a "good" strafing pass. Default is 20.
 -- @param #number foulline (Optional) Foul line distance. Hits from closer than this distance are not counted. Default 610 m = 2000 ft. Set to 0 for no foul line.
 -- @return #RANGE self
@@ -1284,8 +1284,8 @@ end
 --- Add bombing target(s) to range.
 -- @param #RANGE self
 -- @param #table targetnames Single or multiple (Table) names of unit or static objects serving as bomb targets.
--- @param #number goodhitrange (Optional) Max distance from target unit (in meters) which is considered as a good hit. Default is 25 m.
+-- @param #number goodhitrange (Optional) Max hit distance from target unit in meters which is considered as a good hit. Default is 25 m.
--- @param #boolean randommove If true, unit will move randomly within the range. Default is false.
+-- @param #boolean randommove (Optional) If true, unit will move randomly within the range. Default is false.
 -- @return #RANGE self
 function RANGE:AddBombingTargets(targetnames, goodhitrange, randommove)
   self:F({targetnames=targetnames, goodhitrange=goodhitrange, randommove=randommove})
@@ -1323,8 +1323,8 @@ end
 --- Add a unit or static object as bombing target.
 -- @param #RANGE self
 -- @param Wrapper.Positionable#POSITIONABLE unit Positionable (unit or static) of the strafe target.
--- @param #number goodhitrange Max distance from unit which is considered as a good hit.
+-- @param #number goodhitrange (Optional) Max hit distance from target unit in meters which is considered as a good hit. Default is 25 m.
--- @param #boolean randommove If true, unit will move randomly within the range. Default is false.
+-- @param #boolean randommove (Optional) If true, unit will move randomly within the range. Default is false.
 -- @return #RANGE self
 function RANGE:AddBombingTargetUnit(unit, goodhitrange, randommove)
   self:F({unit=unit, goodhitrange=goodhitrange, randommove=randommove})
@@ -1339,7 +1339,7 @@ function RANGE:AddBombingTargetUnit(unit, goodhitrange, randommove)
   goodhitrange=goodhitrange or RANGE.Defaults.goodhitrange
 
   -- Set randommove to false if it was not specified.
-  if randommove==nil or _isstatic==true then
+  if randommove == nil or _isstatic == true then
     randommove=false
   end
 
@@ -1354,7 +1354,7 @@ function RANGE:AddBombingTargetUnit(unit, goodhitrange, randommove)
 
   -- Get max speed of unit in km/h.
   local speed=0
-  if _isstatic==false then
+  if _isstatic == false then
     speed=self:_GetSpeed(unit)
   end
 
@@ -1377,12 +1377,23 @@ function RANGE:AddBombingTargetUnit(unit, goodhitrange, randommove)
   return self
 end
 
---- Add a coordinate of a bombing target. This
+--- Add a coordinate of a bombing target.
 -- @param #RANGE self
 -- @param Core.Point#COORDINATE coord The coordinate.
--- @param #string name Name of target.
+-- @param #string name (Optional) Name of target. Default is "Bomb Target".
--- @param #number goodhitrange Max distance from unit which is considered as a good hit.
+-- @param #number goodhitrange (Optional) Max hit distance from target unit in meters which is considered as a good hit. Default is 25 m.
 -- @return #RANGE self
+-- @usage
+--
+--   -- Setup a Range
+--   RangeOne = RANGE:New( "Range One" )
+--   -- Find the STATIC target object as setup in the ME
+--   RangeOneBombTarget = STATIC:FindByName( "RangeOneBombTarget" ):
+--   -- Add the coordinate of the STATIC target object as a bomb target (thus keeping the bomb function active, even if the STATIC target is destroyed)
+--   RangeOne:AddBombingTargetCoordinate( RangeOneBombTarget:GetCoordinate(), "RangeOneBombTarget", 50)
+--   -- Or, add the coordinate of the STATIC target object as a bomb target using default values (name will be "Bomb Target", goodhitrange will be 25 m)
+--   RangeOne:AddBombingTargetCoordinate( RangeOneBombTarget:GetCoordinate() )
+--
 function RANGE:AddBombingTargetCoordinate(coord, name, goodhitrange)
 
   local target={} --#RANGE.BombTarget
@@ -1403,8 +1414,8 @@ end
 --- Add all units of a group as bombing targets.
 -- @param #RANGE self
 -- @param Wrapper.Group#GROUP group Group of bombing targets.
--- @param #number goodhitrange Max distance from unit which is considered as a good hit.
+-- @param #number goodhitrange (Optional) Max hit distance from target unit in meters which is considered as a good hit. Default is 25 m.
--- @param #boolean randommove If true, unit will move randomly within the range. Default is false.
+-- @param #boolean randommove (Optional) If true, unit will move randomly within the range. Default is false.
 -- @return #RANGE self
 function RANGE:AddBombingTargetGroup(group, goodhitrange, randommove)
   self:F({group=group, goodhitrange=goodhitrange, randommove=randommove})
@@ -1423,10 +1434,10 @@ function RANGE:AddBombingTargetGroup(group, goodhitrange, randommove)
   return self
 end
 
---- Measures the foule line distance between two unit or static objects.
+--- Returns the foul line distance between strafe pit target and a foul line distance marker object.
 -- @param #RANGE self
 -- @param #string namepit Name of the strafe pit target object.
--- @param #string namefoulline Name of the fould line distance marker object.
+-- @param #string namefoulline Name of the foul line distance marker object.
 -- @return #number Foul line distance in meters.
 function RANGE:GetFoullineDistance(namepit, namefoulline)
   self:F({namepit=namepit, namefoulline=namefoulline})
@@ -1437,7 +1448,7 @@ function RANGE:GetFoullineDistance(namepit, namefoulline)
 
   -- Get the unit or static pit object.
   local pit=nil
-  if _staticpit==true then
+  if _staticpit == true then
     pit=STATIC:FindByName(namepit, false)
   elseif _staticpit==false then
     pit=UNIT:FindByName(namepit)
@@ -1447,9 +1458,9 @@ function RANGE:GetFoullineDistance(namepit, namefoulline)
 
   -- Get the unit or static foul line object.
   local foul=nil
-  if _staticfoul==true then
+  if _staticfoul == true then
     foul=STATIC:FindByName(namefoulline, false)
-  elseif _staticfoul==false then
+  elseif _staticfoul == false then
     foul=UNIT:FindByName(namefoulline)
   else
     self:E(self.id..string.format("ERROR! Foul line object %s could not be found in GetFoullineDistance function. Check the name in the ME.", namefoulline))
@@ -1457,7 +1468,7 @@ function RANGE:GetFoullineDistance(namepit, namefoulline)
 
   -- Get the distance between the two objects.
   local fouldist=0
-  if pit~=nil and foul~=nil then
+  if pit ~= nil and foul ~= nil then
     fouldist=pit:GetCoordinate():Get2DDistance(foul:GetCoordinate())
   else
     self:E(self.id..string.format("ERROR! Foul line distance could not be determined. Check pit object name %s and foul line object name %s in the ME.", namepit, namefoulline))
@@ -1552,7 +1563,6 @@ function RANGE:OnEventBirth(EventData)
   self:T3(self.id.."BIRTH: player = "..tostring(_playername))
 
   if _unit and _playername then
-
     local _uid=_unit:GetID()
     local _group=_unit:GetGroup()
     local _gid=_group:GetID()
@@ -1589,8 +1599,8 @@ function RANGE:OnEventBirth(EventData)
       self.timerCheckZone=TIMER:New(self._CheckInZone, self, EventData.IniUnitName):Start(1, 1)
       self.planes[_uid] = true
     end
-
   end
+
 end
 
 --- Range event handler for event hit.
@@ -1607,7 +1617,7 @@ function RANGE:OnEventHit(EventData)
   -- Player info
   local _unitName = EventData.IniUnitName
   local _unit, _playername = self:_GetPlayerUnitAndName(_unitName)
-  if _unit==nil or _playername==nil then
+  if _unit == nil or _playername == nil then
     return
   end
 
@@ -1681,6 +1691,7 @@ function RANGE:OnEventHit(EventData)
       end
     end
   end
+
 end
 
 --- Range event handler for event shot (when a unit releases a rocket or bomb (but not a fast firing gun).
@@ -1690,10 +1701,10 @@ function RANGE:OnEventShot(EventData)
   self:F({eventshot = EventData})
 
   -- Nil checks.
-  if EventData.Weapon==nil then
+  if EventData.Weapon == nil then
     return
   end
-  if EventData.IniDCSUnit==nil then
+  if EventData.IniDCSUnit == nil then
     return
   end
 
@@ -1741,7 +1752,6 @@ function RANGE:OnEventShot(EventData)
 
   -- Only track if distance player to range is < 25 km. Also check that a player shot. No need to track AI weapons.
   if _track and dPR<=self.BombtrackThreshold and _unit and _playername then
-
     -- Player data.
     local playerData=self.PlayerSettings[_playername] --#RANGE.PlayerData
 
@@ -2363,7 +2373,7 @@ function RANGE:_DisplayMyBombingResults(_unitName)
         end
 
         -- Best 10 runs only.
-        if i==self.ndisplayresult then
+        if i == self.ndisplayresult then
           break
         end
 
@@ -3008,7 +3018,7 @@ end
 -- Helper Functions
 -----------------------------------------------------------------------------------------------------------------------------------------------------------------------
 
---- Get the number of shells a unit currently has.
+--- Get the coordinate of a Bomb target.
 -- @param #RANGE self
 -- @param #RANGE.BombTarget target Bomb target data.
 -- @return Core.Point#COORDINATE Target coordinate.
@@ -3016,7 +3026,7 @@ function RANGE:_GetBombTargetCoordinate(target)
 
   local coord=nil --Core.Point#COORDINATE
 
-  if target.type==RANGE.TargetType.UNIT then
+  if target.type == RANGE.TargetType.UNIT then
 
     if not target.move then
       -- Target should not move.
@@ -3028,12 +3038,12 @@ function RANGE:_GetBombTargetCoordinate(target)
       end
     end
 
-  elseif target.type==RANGE.TargetType.STATIC then
+  elseif target.type == RANGE.TargetType.STATIC then
 
     -- Static targets dont move.
     coord=target.coordinate
 
-  elseif target.type==RANGE.TargetType.COORD then
+  elseif target.type == RANGE.TargetType.COORD then
 
     -- Coordinates dont move.
     coord=target.coordinate

Moose Development/Moose/Wrapper/Static.lua

@@ -10,11 +10,8 @@
 --
 -- @module Wrapper.Static
 -- @image Wrapper_Static.JPG
-
-
 --- @type STATIC
 -- @extends Wrapper.Positionable#POSITIONABLE
-
 --- Wrapper class to handle Static objects.
 --
 -- Note that Statics are almost the same as Units, but they don't have a controller.
@@ -40,13 +37,10 @@
 --
 --  * @{#STATIC.FindByName}(): Find a STATIC instance from the _DATABASE object using a DCS Static name.
 --
--- IMPORTANT: ONE SHOULD NEVER SANATIZE these STATIC OBJECT REFERENCES! (make the STATIC object references nil).
+-- IMPORTANT: ONE SHOULD NEVER SANITIZE these STATIC OBJECT REFERENCES! (make the STATIC object references nil).
 --
 -- @field #STATIC
-STATIC = {
+STATIC = { ClassName = "STATIC" }
-	ClassName = "STATIC",
-}
-
 
 --- Register a static object.
 -- @param #STATIC self
@@ -58,7 +52,6 @@ function STATIC:Register( StaticName )
   return self
 end
 
-
 --- Finds a STATIC from the _DATABASE using a DCSStatic object.
 -- @param #STATIC self
 -- @param DCS#StaticObject DCSStatic An existing DCS Static object reference.
@@ -97,8 +90,9 @@ end
 
 --- Destroys the STATIC.
 -- @param #STATIC self
--- @param #boolean GenerateEvent (Optional) true if you want to generate a crash or dead event for the static.
+-- @param #boolean GenerateEvent (Optional) true to generate a crash or dead event, false to not generate any event. `nil` (default) creates a remove event.
 -- @return #nil The DCS StaticObject is not existing or alive.
+--
 -- @usage
 -- -- Air static example: destroy the static Helicopter and generate a S_EVENT_CRASH.
 -- Helicopter = STATIC:FindByName( "Helicopter" )
@@ -117,7 +111,7 @@ end
 -- @usage
 -- -- Destroy without event generation example.
 -- Ship = STATIC:FindByName( "Boat" )
--- Ship:Destroy( false ) -- Don't generate an event upon destruction.
+-- Ship:Destroy( false ) -- Don't generate any event upon destruction.
 --
 function STATIC:Destroy( GenerateEvent )
   self:F2( self.ObjectName )
@@ -148,7 +142,6 @@ function STATIC:Destroy( GenerateEvent )
   return nil
 end
 
-
 --- Get DCS object of static of static.
 -- @param #STATIC self
 -- @return DCS static object
@@ -180,7 +173,6 @@ function STATIC:GetUnits()
   return nil
 end
 
-
 --- Get threat level of static.
 -- @param #STATIC self
 -- @return #number Threat level 1.
@@ -194,15 +186,15 @@ end
 -- @param Core.Point#COORDINATE Coordinate The coordinate where to spawn the new Static.
 -- @param #number Heading The heading of the static respawn in degrees. Default is 0 deg.
 -- @param #number Delay Delay in seconds before the static is spawned.
-function STATIC:SpawnAt(Coordinate, Heading, Delay)
+function STATIC:SpawnAt( Coordinate, Heading, Delay )
 
-  Heading=Heading or 0
+  Heading = Heading or 0
 
-  if Delay and Delay>0 then
+  if Delay and Delay > 0 then
-    SCHEDULER:New(nil, self.SpawnAt, {self, Coordinate, Heading}, Delay)
+    SCHEDULER:New( nil, self.SpawnAt, { self, Coordinate, Heading }, Delay )
   else
 
-    local SpawnStatic=SPAWNSTATIC:NewFromStatic(self.StaticName)
+    local SpawnStatic = SPAWNSTATIC:NewFromStatic( self.StaticName )
 
     SpawnStatic:SpawnFromPointVec2( Coordinate, Heading, self.StaticName )
 
@@ -211,47 +203,43 @@ function STATIC:SpawnAt(Coordinate, Heading, Delay)
   return self
 end
 
-
 --- Respawn the @{Wrapper.Unit} at the same location with the same properties.
 -- This is useful to respawn a cargo after it has been destroyed.
 -- @param #STATIC self
 -- @param DCS#country.id CountryID (Optional) The country ID used for spawning the new static. Default is same as currently.
 -- @param #number Delay (Optional) Delay in seconds before static is respawned. Default now.
-function STATIC:ReSpawn(CountryID, Delay)
+function STATIC:ReSpawn( CountryID, Delay )
 
-  if Delay and Delay>0 then
+  if Delay and Delay > 0 then
-    SCHEDULER:New(nil, self.ReSpawn, {self, CountryID}, Delay)
+    SCHEDULER:New( nil, self.ReSpawn, { self, CountryID }, Delay )
   else
 
-    CountryID=CountryID or self:GetCountry()  
+    CountryID = CountryID or self:GetCountry()
 
-    local SpawnStatic=SPAWNSTATIC:NewFromStatic(self.StaticName, CountryID)
+    local SpawnStatic = SPAWNSTATIC:NewFromStatic( self.StaticName, CountryID )
 
-    SpawnStatic:Spawn(nil, self.StaticName)
+    SpawnStatic:Spawn( nil, self.StaticName )
 
   end
 
   return self
 end
 
-
 --- Respawn the @{Wrapper.Unit} at a defined Coordinate with an optional heading.
 -- @param #STATIC self
 -- @param Core.Point#COORDINATE Coordinate The coordinate where to spawn the new Static.
--- @param #number Heading (Optional) The heading of the static respawn in degrees. Default the current heading.
+-- @param #number Heading (Optional) The heading of the static respawn in degrees. Default is the current heading.
--- @param #number Delay (Optional) Delay in seconds before static is respawned. Default now.
+-- @param #number Delay (Optional) Delay in seconds before static is respawned. Default is now.
-function STATIC:ReSpawnAt(Coordinate, Heading, Delay)
+function STATIC:ReSpawnAt( Coordinate, Heading, Delay )
 
-  --Heading=Heading or 0
+  -- Heading=Heading or 0
 
-  if Delay and Delay>0 then
+  if Delay and Delay > 0 then
-    SCHEDULER:New(nil, self.ReSpawnAt, {self, Coordinate, Heading}, Delay)
+    SCHEDULER:New( nil, self.ReSpawnAt, { self, Coordinate, Heading }, Delay )
   else
+    local SpawnStatic = SPAWNSTATIC:NewFromStatic( self.StaticName, self:GetCountry() )
 
-    local SpawnStatic=SPAWNSTATIC:NewFromStatic(self.StaticName, self:GetCountry())
+    SpawnStatic:SpawnFromCoordinate( Coordinate, Heading, self.StaticName )
-    
-    SpawnStatic:SpawnFromCoordinate(Coordinate, Heading, self.StaticName)
-    
   end
 
   return self

Moose Development/Moose/Wrapper/Unit.lua

@@ -168,9 +168,6 @@ function UNIT:GetDCSObject()
   return nil
 end
 
-
-
-
 --- Respawn the @{Wrapper.Unit} using a (tweaked) template of the parent Group.
 -- 
 -- This function will:
@@ -263,8 +260,6 @@ function UNIT:ReSpawnAt( Coordinate, Heading )
   _DATABASE:Spawn( SpawnGroupTemplate )
 end
 
-
-
 --- Returns if the unit is activated.
 -- @param #UNIT self
 -- @return #boolean `true` if Unit is activated. `nil` The DCS Unit is not existing or alive.  
@@ -301,8 +296,6 @@ function UNIT:IsAlive()
   return nil
 end
 
-
-
 --- Returns the Unit's callsign - the localized string.
 -- @param #UNIT self
 -- @return #string The Callsign of the Unit.
@@ -961,7 +954,6 @@ end
 -- @return #string Some text.
 function UNIT:GetThreatLevel()
 
-
   local ThreatLevel = 0
   local ThreatText = ""
   
@@ -987,7 +979,6 @@ function UNIT:GetThreatLevel()
         "LR SAMs"
       }
       
-      
       if     Attributes["LR SAM"]                                                     then ThreatLevel = 10
       elseif Attributes["MR SAM"]                                                     then ThreatLevel = 9
       elseif Attributes["SR SAM"] and
@@ -1023,7 +1014,6 @@ function UNIT:GetThreatLevel()
         "Fighter"
       }
       
-      
       if     Attributes["Fighters"]                                 then ThreatLevel = 10
       elseif Attributes["Multirole fighters"]                       then ThreatLevel = 9
       elseif Attributes["Battleplanes"]                             then ThreatLevel = 8
@@ -1141,12 +1131,6 @@ function UNIT:OtherUnitInRadius( AwaitUnit, Radius )
 	return nil
 end
 
-
-
-
-
-
-
 --- Returns if the unit is a friendly unit.
 -- @param #UNIT self
 -- @return #boolean IsFriendly evaluation result.