Range re-formatting and documentation re-fixing (#1691)

* Update Range.lua

Code formatting.

* RANGE - Documentation fixes.

Moose Development/Moose/Functional/Range.lua

@@ -19,7 +19,7 @@
 --   * Bomb, rocket and missile impact points can be marked by smoke.
 --   * Direct hits on targets can trigger flares.
 --   * Smoke and flare colors can be adjusted for each player via radio menu.
---   * Range information and weather report at the range can be reported via radio menu.
+--   * Range information and weather at the range can be obtained via radio menu.
 --   * Persistence: Bombing range results can be saved to disk and loaded the next time the mission is started.
 --   * Range control voice overs (>40) for hit assessment.
 --
@@ -50,11 +50,10 @@
 -- @module Functional.Range
 -- @image Range.JPG
 
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 --- RANGE class
 -- @type RANGE
 -- @field #string ClassName Name of the Class.
--- @field #boolean Debug If true, debug info is send as messages on the screen.
+-- @field #boolean Debug If true, debug info is sent as messages on the screen.
 -- @field #boolean verbose Verbosity level. Higher means more output to DCS log file.
 -- @field #string id String id of range for output in DCS log.
 -- @field #string rangename Name of the range.
@@ -77,13 +76,13 @@
 -- @field #number Tmsg Time [sec] messages to players are displayed. Default 30 sec.
 -- @field #string examinergroupname Name of the examiner group which should get all messages.
 -- @field #boolean examinerexclusive If true, only the examiner gets messages. If false, clients and examiner get messages.
--- @field #number strafemaxalt Maximum altitude above ground for registering for a strafe run. Default is 914 m = 3000 ft.
+-- @field #number strafemaxalt Maximum altitude in meters AGL for registering for a strafe run. Default is 914 m = 3000 ft.
 -- @field #number ndisplayresult Number of (player) results that a displayed. Default is 10.
 -- @field Utilities.Utils#SMOKECOLOR BombSmokeColor Color id used for smoking bomb targets.
 -- @field Utilities.Utils#SMOKECOLOR StrafeSmokeColor Color id used to smoke strafe targets.
 -- @field Utilities.Utils#SMOKECOLOR StrafePitSmokeColor Color id used to smoke strafe pit approach boxes.
--- @field #number illuminationminalt Minimum altitude AGL in meters at which illumination bombs are fired. Default is 500 m.
+-- @field #number illuminationminalt Minimum altitude in meters AGL at which illumination bombs are fired. Default is 500 m.
--- @field #number illuminationmaxalt Maximum altitude AGL in meters at which illumination bombs are fired. Default is 1000 m.
+-- @field #number illuminationmaxalt Maximum altitude in meters AGL at which illumination bombs are fired. Default is 1000 m.
 -- @field #number scorebombdistance Distance from closest target up to which bomb hits are counted. Default 1000 m.
 -- @field #number TdelaySmoke Time delay in seconds between impact of bomb and starting the smoke. Default 3 seconds.
 -- @field #boolean eventmoose If true, events are handled by MOOSE. If false, events are handled directly by DCS eventhandler. Default true.
@@ -134,12 +133,12 @@
 --
 -- A strafe pit can be added to the range by the @{#RANGE.AddStrafePit}(*targetnames, boxlength, boxwidth, heading, inverseheading, goodpass, foulline*) function.
 --
--- * The first parameter *targetnames* defines the target or targets. This has to be given as a lua table which contains the names of @{Wrapper.Unit} or @{Static} objects defined in the mission editor.
+-- * 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.
 -- * In order to perform a valid pass on the strafe pit, the pilot has to begin his run from the correct direction. Therefore, an "approach box" is defined in front
---   of the strafe targets. The parameters *boxlength* and *boxwidth* define the size of the box while the parameter *heading* defines its direction.
+--   of the strafe targets. The parameters *boxlength* and *boxwidth* define the size of the box in meters, while the *heading* parameter defines the heading of the box FROM the target.
---   If the parameter *heading* is passed as **nil**, the heading is automatically taken from the heading of the first target unit as defined in the ME.
+--   For example, if heading 120 is set, the approach box will start FROM the target and extend outwards on heading 120. A strafe run approach must then be flown apx. heading 300 TOWARDS the target.
---   The parameter *inverseheading* turns the heading around by 180 degrees. This is sometimes useful, since the default heading of strafe target units point in the
+--   If the parameter *heading* is passed as **nil**, the heading is automatically taken from the heading set in the ME for the first target unit.
---   wrong/opposite direction.
+-- * The parameter *inverseheading* turns the heading around by 180 degrees. This is useful when the default heading of strafe target units point in the wrong/opposite direction.
 -- * The parameter *goodpass* defines the number of hits a pilot has to achieve during a run to be judged as a "good" pass.
 -- * The last parameter *foulline* sets the distance from the pit targets to the foul line. Hit from closer than this line are not counted!
 --
@@ -153,9 +152,8 @@
 --
 -- One ore multiple bombing targets can be added to the range by the @{#RANGE.AddBombingTargets}(targetnames, goodhitrange, randommove) function.
 --
--- * The first parameter *targetnames* has to be a lua table, which contains the names of @{Wrapper.Unit} and/or @{Static} objects defined in the mission editor.
+-- * 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.
---   Note that the @{Range} logic **automatically** determines, if a name belongs to a @{Wrapper.Unit} or @{Static} object now.
+-- * The (optional) parameter *goodhitrange* specifies the radius in metres around the target within which a bomb/rocket hit is considered to be "good".
--- * The (optional) parameter *goodhitrange* specifies the radius around the target. If a bomb or rocket falls at a distance smaller than this number, the 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.
 --   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.
 --
@@ -191,7 +189,7 @@
 --
 -- The main range menu can be found at "F10. Other..." --> "F*X*. On the Range..." --> "F1. <Range Name>...".
 --
--- The range menu contains the following submenues:
+-- The range menu contains the following submenus:
 --
 -- ![Banner Image](..\Presentations\RANGE\Menu_Main.png)
 --
@@ -258,9 +256,9 @@
 --      -- Note that this could also be done manually by simply measuring the distance between the target and the foul line in the ME.
 --      GoldwaterRange:GetFoullineDistance("GWR Strafe Pit Left 1", "GWR Foul Line Left")
 --
---      -- Add strafe pits. Each pit (left and right) consists of two targets.
+--      -- Add strafe pits. Each pit (left and right) consists of two targets. Where "nil" is used as input, the default value is used.
---      GoldwaterRange:AddStrafePit(strafepit_left, 3000, 300, nil, true, 20, fouldist)
+--      GoldwaterRange:AddStrafePit(strafepit_left, 3000, 300, nil, true, 30, 500)
---      GoldwaterRange:AddStrafePit(strafepit_right, nil, nil, nil, true, nil, fouldist)
+--      GoldwaterRange:AddStrafePit(strafepit_right, nil, nil, nil, true, nil, 500)
 --
 --      -- Add bombing targets. A good hit is if the bomb falls less then 50 m from the target.
 --      GoldwaterRange:AddBombingTargets(bombtargets, 50)
@@ -290,8 +288,6 @@
 -- Note that it can happen that the RANGE radio menu is not shown. Check that the range object is defined as a **global** variable rather than a local one.
 -- The could avoid the lua garbage collection to accidentally/falsely deallocate the RANGE objects.
 --
---
---
 -- @field #RANGE
 RANGE = {
   ClassName = "RANGE",
@@ -356,8 +352,7 @@ RANGE.Defaults={
   boxlength = 3000,
   boxwidth = 300,
   goodpass = 20,
-  goodhitrange=25,
+  foulline = 610
-  foulline=610,
 }
 
 --- Target type, i.e. unit, static, or coordinate.
@@ -368,7 +363,7 @@ RANGE.Defaults={
 RANGE.TargetType = {
   UNIT = "Unit",
   STATIC = "Static",
-  COORD="Coordinate",
+  COORD = "Coordinate"
 }
 
 --- Default range variables for RangeBoss/Hypeman tie in.
@@ -378,6 +373,7 @@ Straferesult={}
 clientRollingIn = false
 clientStrafed = false
 invalidStrafe = false
+
 --- Player settings.
 -- @type RANGE.PlayerData
 -- @field #boolean smokebombimpact Smoke bomb impact points.
@@ -847,7 +843,7 @@ end
 
 --- Set maximal strafing altitude. Player entering a strafe pit above that altitude are not registered for a valid pass.
 -- @param #RANGE self
--- @param #number maxalt Maximum altitude AGL in meters. Default is 914 m= 3000 ft.
+-- @param #number maxalt Maximum altitude in meters AGL. Default is 914 m = 3000 ft.
 -- @return #RANGE self
 function RANGE:SetMaxStrafeAlt( maxalt )
   self.strafemaxalt = maxalt or RANGE.Defaults.strafemaxalt
@@ -1052,7 +1048,6 @@ function RANGE:SetMessagesON()
   return self
 end
 
-
 --- Enables tracking of all bomb types. Note that this is the default setting.
 -- @param #RANGE self
 -- @return #RANGE self
@@ -1101,7 +1096,6 @@ function RANGE:TrackMissilesOFF()
   return self
 end
 
-
 --- Enable range control and set frequency.
 -- @param #RANGE self
 -- @param #number frequency Frequency in MHz. Default 256 MHz.
@@ -1126,7 +1120,7 @@ end
 
 --- Set sound files folder within miz file.
 -- @param #RANGE self
--- @param #string path Path for sound files. Default "ATIS Soundfiles/". Mind the slash "/" at the end!
+-- @param #string path Path for sound files. Default "Range Soundfiles/". Mind the slash "/" at the end!
 -- @return #RANGE self
 function RANGE:SetSoundfilesPath( path )
   self.soundpath = tostring( path or "Range Soundfiles/" )
@@ -1135,16 +1129,16 @@ function RANGE:SetSoundfilesPath(path)
 end
 
 --- Add new strafe pit. For a strafe pit, hits from guns are counted. One pit can consist of several units.
--- Note, an approach is only valid, if the player enters via a zone in front of the pit, which defined by boxlength and boxheading.
+-- A strafe run approach is only valid if the player enters via a zone in front of the pit, which is defined by boxlength, boxwidth, and heading.
 -- Furthermore, the player must not be too high and fly in the direction of the pit to make a valid target apporoach.
 -- @param #RANGE self
--- @param #table targetnames Table of unit or static names defining the strafe targets. The first target in the list determines the approach zone (heading and box).
+-- @param #table targetnames Single or multiple (Table) unit or static names defining the strafe targets. The first target in the list determines the approach box origin (heading and box).
 -- @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 #number heading (Optional) Approach box heading in degrees (originating FROM the target). Default is the heading set in the ME for the first target unit
--- @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.
+-- @param #number foulline (Optional) Foul line distance. Hits from closer than this distance are not counted. Default is 610 m = 2000 ft. Set to 0 for no foul line.
 -- @return #RANGE self
 function RANGE:AddStrafePit( targetnames, boxlength, boxwidth, heading, inverseheading, goodpass, foulline )
   self:F( { targetnames = targetnames, boxlength = boxlength, boxwidth = boxwidth, heading = heading, inverseheading = inverseheading, goodpass = goodpass, foulline = foulline } )
@@ -1274,7 +1268,6 @@ function RANGE:AddStrafePit(targetnames, boxlength, boxwidth, heading, inversehe
   return self
 end
 
-
 --- Add all units of a group as one new strafe target pit.
 -- For a strafe pit, hits from guns are counted. One pit can consist of several units.
 -- Note, an approach is only valid, if the player enters via a zone in front of the pit, which defined by boxlength and boxheading.
@@ -1318,7 +1311,7 @@ end
 
 --- Add bombing target(s) to range.
 -- @param #RANGE self
--- @param #table targetnames Table containing names of unit or static objects serving as bomb targets.
+-- @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 #boolean randommove If true, unit will move randomly within the range. Default is false.
 -- @return #RANGE self
@@ -1412,7 +1405,6 @@ function RANGE:AddBombingTargetUnit(unit, goodhitrange, randommove)
   return self
 end
 
-
 --- Add a coordinate of a bombing target. This
 -- @param #RANGE self
 -- @param Core.Point#COORDINATE coord The coordinate.
@@ -1574,7 +1566,6 @@ function RANGE:onEvent(Event)
 
 end
 
-
 --- Range event handler for event birth.
 -- @param #RANGE self
 -- @param Core.Event#EVENTDATA EventData
@@ -1793,8 +1784,7 @@ function RANGE:OnEventShot(EventData)
     local function trackBomb( _ordnance )
 
       -- When the pcall returns a failure the weapon has hit.
-      local _status,_bombPos =  pcall(
+      local _status, _bombPos = pcall( function()
-      function()
         return _ordnance:getPoint()
       end )
 
@@ -1955,7 +1945,6 @@ function RANGE:_SaveTargetSheet(_playername, result) --RangeBoss Specific Functi
     end
   end
 
-
   -- Set path or default.
   local path = self.targetpath
   if lfs then
@@ -2007,7 +1996,6 @@ function RANGE:_SaveTargetSheet(_playername, result) --RangeBoss Specific Functi
   end
   data = data .. string.format( "%s,%s,%.2f,%03d,%s,%03d,%03d,%s,%03d,%s,%s,%s,%s", _playername, target, distance, radial, quality, roundsFired, roundsHit, strafeResult, attackHeading, weapon, airframe, time, date )
 
-
   -- Save file.
   _savefile( filename, data )
 end
@@ -2047,7 +2035,6 @@ function RANGE:onafterStatus(From, Event, To)
       text = text .. string.format( ", Control %.3f MHz (Relay=%s alive=%s)", self.rangecontrolfreq, tostring( self.rangecontrolrelayname ), alive )
     end
 
-  
     -- Check range status.
     self:I( self.id .. text )
 
@@ -2099,7 +2086,6 @@ function RANGE:onafterExitRange(From, Event, To, player)
 
 end
 
-
 --- Function called after bomb impact on range.
 -- @param #RANGE self
 -- @param #string From From state.
@@ -2347,7 +2333,9 @@ function RANGE:_DisplayMyStrafePitResults(_unitName)
     else
 
       -- Sort results table wrt number of hits.
-      local _sort = function( a,b ) return a.hits > b.hits end
+      local _sort = function( a, b )
+        return a.hits > b.hits
+      end
       table.sort( _results, _sort )
 
       -- Prepare message of best results.
@@ -2421,7 +2409,9 @@ function RANGE:_DisplayStrafePitResults(_unitName)
     end
 
     -- Sort list!
-    local _sort = function( a,b ) return a.hits > b.hits end
+    local _sort = function( a, b )
+      return a.hits > b.hits
+    end
     table.sort( _playerResults, _sort )
 
     -- Add top 10 results.
@@ -2462,7 +2452,9 @@ function RANGE:_DisplayMyBombingResults(_unitName)
     else
 
       -- Sort results wrt to distance.
-      local _sort = function( a,b ) return a.distance < b.distance end
+      local _sort = function( a, b )
+        return a.distance < b.distance
+      end
       table.sort( _results, _sort )
 
       -- Loop over results.
@@ -2532,7 +2524,9 @@ function RANGE:_DisplayBombingResults(_unitName)
     end
 
     -- Sort list of player results.
-    local _sort = function( a,b ) return a.distance < b.distance end
+    local _sort = function( a, b )
+      return a.distance < b.distance
+    end
     table.sort( _playerResults, _sort )
 
     -- Loop over player results.
@@ -2721,7 +2715,6 @@ function RANGE:_DisplayStrafePits(_unitname)
   end
 end
 
-
 --- Report weather conditions at range. Temperature, QFE pressure and wind data.
 -- @param #RANGE self
 -- @param #string _unitname Name of the player unit.
@@ -2767,7 +2760,6 @@ function RANGE:_DisplayRangeWeather(_unitname)
         tP = string.format( "%.2f inHg", P * hPa2inHg )
       end
 
-
       -- Message text.
       text = text .. string.format( "Weather Report at %s:\n", self.rangename )
       text = text .. string.format( "--------------------------------------------------\n" )
@@ -2940,7 +2932,9 @@ function RANGE:_CheckInZone(_unitName)
           local accur = 0
           if shots > 0 then
             accur = _result.hits / shots * 100
-            if accur > 100 then accur = 100 end
+            if accur > 100 then
+              accur = 100
+            end
           end
 
           if invalidStrafe == true then --
@@ -3232,7 +3226,6 @@ function RANGE:_GetBombTargetCoordinate(target)
   return coord
 end
 
-
 --- Get the number of shells a unit currently has.
 -- @param #RANGE self
 -- @param #string unitname Name of the player unit.
@@ -3801,7 +3794,7 @@ function RANGE:_GetPlayerUnitAndName(_unitName)
   return nil, nil
 end
 
---- Returns a string which consits of this callsign and the player name.
+--- Returns a string which consists of the player name.
 -- @param #RANGE self
 -- @param #string unitname Name of the player unit.
 function RANGE:_myname( unitname )
@@ -3809,7 +3802,7 @@ function RANGE:_myname(unitname)
 
   local unit = UNIT:FindByName( unitname )
   local pname = unit:GetPlayerName()
-  local csign=unit:GetCallsign()
+  -- local csign = unit:GetCallsign()
 
   -- return string.format("%s (%s)", csign, pname)
   return string.format( "%s", pname )