Added documentation in SPAWN

-- Added documentation for methods GetFirstAliveGroup,
GetNextAliveGroup, GetLastAliveGroup.
-- Added code snippets to the documentation for the methods
GetFirstAliveGroup, GetNextAliveGroup, GetLastAliveGroup.

Moose Development/Moose/Spawn.lua

@@ -7,7 +7,7 @@
 -- A reference to this Spawn Template needs to be provided when constructing the SPAWN object, by indicating the name of the group within the mission editor in the constructor methods.
 -- 
 -- Within the SPAWN object, there is an internal index that keeps track of which group from the internal group list was spawned. 
--- When new groups get spawned by using the SPAWN functions (see below), it will be validated whether the Limits (@{#SPAWN.Limit}) of the SPAWN object are not reached.
+-- When new groups get spawned by using the SPAWN methods (see below), it will be validated whether the Limits (@{#SPAWN.Limit}) of the SPAWN object are not reached.
 -- When all is valid, a new group will be created by the spawning methods, and the internal index will be increased with 1.
 -- 
 -- Regarding the name of new spawned groups, a _SpawnPrefix_ will be assigned for each new group created. 
@@ -28,10 +28,10 @@
 -- -------------------------------
 -- Create a new SPAWN object with the @{#SPAWN.New} or the @{#SPAWN.NewWithAlias} methods:
 -- 
---   * @{#SPAWN.New}: Creates a new SPAWN object taking the name of the group that functions as the Template.
+--   * @{#SPAWN.New}: Creates a new SPAWN object taking the name of the group that represents the GROUP Template (definition).
 --
 -- It is important to understand how the SPAWN class works internally. The SPAWN object created will contain internally a list of groups that will be spawned and that are already spawned.
--- The initialization functions will modify this list of groups so that when a group gets spawned, ALL information is already prepared when spawning. This is done for performance reasons.
+-- The initialization methods will modify this list of groups so that when a group gets spawned, ALL information is already prepared when spawning. This is done for performance reasons.
 -- So in principle, the group list will contain all parameters and configurations after initialization, and when groups get actually spawned, this spawning can be done quickly and efficient.
 --
 -- 1.2) SPAWN initialization methods
@@ -43,7 +43,7 @@
 --   * @{#SPAWN.RandomizeTemplate}: Randomize the group templates so that when a new group is spawned, a random group template is selected from one of the templates defined. 
 --   * @{#SPAWN.Uncontrolled}: Spawn plane groups uncontrolled.
 --   * @{#SPAWN.Array}: Make groups visible before they are actually activated, and order these groups like a batallion in an array.
---   * @{#SPAWN.InitRepeat}: Re-spawn groups when they land at the home base. Similar functions are @{#SPAWN.InitRepeatOnLanding} and @{#SPAWN.InitRepeatOnEngineShutDown}.
+--   * @{#SPAWN.InitRepeat}: Re-spawn groups when they land at the home base. Similar methods are @{#SPAWN.InitRepeatOnLanding} and @{#SPAWN.InitRepeatOnEngineShutDown}.
 -- 
 -- 1.3) SPAWN spawning methods
 -- ---------------------------
@@ -61,7 +61,20 @@
 -- Note that @{#SPAWN.Spawn} and @{#SPAWN.ReSpawn} return a @{GROUP#GROUP.New} object, that contains a reference to the DCSGroup object. 
 -- You can use the @{GROUP} object to do further actions with the DCSGroup.
 --  
--- 1.4) SPAWN object cleaning
+-- 1.4) Retrieve alive GROUPs spawned by the SPAWN object
+-- ------------------------------------------------------
+-- The SPAWN class administers which GROUPS it has reserved (in stock) or has created during mission execution.
+-- Every time a SPAWN object spawns a new GROUP object, a reference to the GROUP object is added to an internal table of GROUPS.
+-- SPAWN provides methods to iterate through that internal GROUP object reference table:
+-- 
+--   * @{#SPAWN.GetFirstAliveGroup}: Will find the first alive GROUP it has spawned, and return the alive GROUP object and the first Index where the first alive GROUP object has been found.
+--   * @{#SPAWN.GetNextAliveGroup}: Will find the next alive GROUP object from a given Index, and return a reference to the alive GROUP object and the next Index where the alive GROUP has been found.
+--   * @{#SPAWN.GetLastAliveGroup}: Will find the last alive GROUP object, and will return a reference to the last live GROUP object and the last Index where the last alive GROUP object has been found.
+-- 
+-- You can use the methods @{#SPAWN.GetFirstAliveGroup} and sequently @{#SPAWN.GetNextAliveGroup} to iterate through the alive GROUPS within the SPAWN object, and to actions... See the respective methods for an example.
+-- The method @{#SPAWN.GetGroupFromIndex} will return the GROUP object reference from the given Index, dead or alive...
+-- 
+-- 1.5) SPAWN object cleaning
 -- --------------------------
 -- Sometimes, it will occur during a mission run-time, that ground or especially air objects get damaged, and will while being damged stop their activities, while remaining alive.
 -- In such cases, the SPAWN object will just sit there and wait until that group gets destroyed, but most of the time it won't, 
@@ -727,19 +740,24 @@ function SPAWN:SpawnGroupName( SpawnIndex )
 	
 end
 
---- Find the first alive group.
+--- Will find the first alive GROUP it has spawned, and return the alive GROUP object and the first Index where the first alive GROUP object has been found.
 -- @param #SPAWN self
--- @param #number SpawnCursor A number holding the index from where to find the first group from.
--- @return Group#GROUP, #number The group found, the new index where the group was found.
+-- @return Group#GROUP, #number The GROUP object found, the new Index where the group was found.
 -- @return #nil, #nil When no group is found, #nil is returned.
-function SPAWN:GetFirstAliveGroup( SpawnCursor )
-	self:F( { self.SpawnTemplatePrefix, self.SpawnAliasPrefix, SpawnCursor } )
+-- @usage
+-- -- Find the first alive GROUP object of the SpawnPlanes SPAWN object GROUP collection that it has spawned during the mission.
+-- local GroupPlane, Index = SpawnPlanes:GetFirstAliveGroup()
+-- while GroupPlane ~= nil do
+--   -- Do actions with the GroupPlane object.
+--   GroupPlane, Index = SpawnPlanes:GetNextAliveGroup( Index )
+-- end
+function SPAWN:GetFirstAliveGroup()
+	self:F( { self.SpawnTemplatePrefix, self.SpawnAliasPrefix } )
 
   for SpawnIndex = 1, self.SpawnCount do
     local SpawnGroup = self:GetGroupFromIndex( SpawnIndex )
     if SpawnGroup and SpawnGroup:IsAlive() then
-      SpawnCursor = SpawnIndex
-      return SpawnGroup, SpawnCursor
+      return SpawnGroup, SpawnIndex
     end
   end
   
@@ -747,27 +765,42 @@ function SPAWN:GetFirstAliveGroup( SpawnCursor )
 end
 
 
---- Find the next alive group.
+--- Will find the next alive GROUP object from a given Index, and return a reference to the alive GROUP object and the next Index where the alive GROUP has been found.
 -- @param #SPAWN self
--- @param #number SpawnCursor A number holding the last found previous index.
--- @return Group#GROUP, #number The group found, the new index where the group was found.
--- @return #nil, #nil When no group is found, #nil is returned.
-function SPAWN:GetNextAliveGroup( SpawnCursor )
-	self:F( { self.SpawnTemplatePrefix, self.SpawnAliasPrefix, SpawnCursor } )
+-- @param #number SpawnIndexStart A Index holding the start position to search from. This function can also be used to find the first alive GROUP object from the given Index.
+-- @return Group#GROUP, #number The next alive GROUP object found, the next Index where the next alive GROUP object was found.
+-- @return #nil, #nil When no alive GROUP object is found from the start Index position, #nil is returned.
+-- @usage
+-- -- Find the first alive GROUP object of the SpawnPlanes SPAWN object GROUP collection that it has spawned during the mission.
+-- local GroupPlane, Index = SpawnPlanes:GetFirstAliveGroup()
+-- while GroupPlane ~= nil do
+--   -- Do actions with the GroupPlane object.
+--   GroupPlane, Index = SpawnPlanes:GetNextAliveGroup( Index )
+-- end
+function SPAWN:GetNextAliveGroup( SpawnIndexStart )
+	self:F( { self.SpawnTemplatePrefix, self.SpawnAliasPrefix, SpawnIndexStart } )
 
-  SpawnCursor = SpawnCursor + 1
-  for SpawnIndex = SpawnCursor, self.SpawnCount do
+  SpawnIndexStart = SpawnIndexStart + 1
+  for SpawnIndex = SpawnIndexStart, self.SpawnCount do
     local SpawnGroup = self:GetGroupFromIndex( SpawnIndex )
     if SpawnGroup and SpawnGroup:IsAlive() then
-      SpawnCursor = SpawnIndex
-      return SpawnGroup, SpawnCursor
+      return SpawnGroup, SpawnIndex
     end
   end
   
   return nil, nil
 end
 
---- Find the last alive group during runtime.
+--- Will find the last alive GROUP object, and will return a reference to the last live GROUP object and the last Index where the last alive GROUP object has been found.
+-- @param #SPAWN self
+-- @return Group#GROUP, #number The last alive GROUP object found, the last Index where the last alive GROUP object was found.
+-- @return #nil, #nil When no alive GROUP object is found, #nil is returned.
+-- @usage
+-- -- Find the last alive GROUP object of the SpawnPlanes SPAWN object GROUP collection that it has spawned during the mission.
+-- local GroupPlane, Index = SpawnPlanes:GetLastAliveGroup()
+-- if GroupPlane then -- GroupPlane can be nil!!!
+--   -- Do actions with the GroupPlane object.
+-- end
 function SPAWN:GetLastAliveGroup()
 	self:F( { self.SpawnTemplatePrefixself.SpawnAliasPrefix } )