Updated luadoc documentation

BASE
CLIENT

Moose/Base.lua

@@ -1,6 +1,6 @@
---- BASE The base class for all the classes defined within MOOSE.
+--- The BASE class for all the classes defined within MOOSE.
 -- @module Base
--- @author Flightcontrol
+-- @author FlightControl
 
 Include.File( "Routines" )
 
@@ -33,7 +33,6 @@ local _TraceClass = {
 -- @field ClassName The name of the class.
 -- @field ClassID The ID number of the class.
 BASE = {
-
   ClassName = "BASE",
   ClassID = 0,
   Events = {}
@@ -48,8 +47,8 @@ FORMATION = {
 
 --- The base constructor. This is the top top class of all classed defined within the MOOSE.
 -- Any new class needs to be derived from this class for proper inheritance.
--- @param self
+-- @param #BASE self
--- @return #BASE
+-- @return #BASE The new instance of the BASE class.
 -- @usage
 -- function TASK:New()
 --
@@ -76,9 +75,10 @@ function BASE:New()
 end
 
 --- This is the worker method to inherit from a parent class.
+-- @param #BASE self
 -- @param Child is the Child class that inherits.
--- @param Parent is the Parent class that the Child inherits from.
+-- @param #BASE Parent is the Parent class that the Child inherits from.
--- @return Child
+-- @return #BASE Child
 function BASE:Inherit( Child, Parent )
 	local Child = routines.utils.deepCopy( Child )
 	local Parent = routines.utils.deepCopy( Parent )
@@ -92,6 +92,7 @@ function BASE:Inherit( Child, Parent )
 end
 
 --- This is the worker method to retrieve the Parent class.
+-- @param #BASE self
 -- @param #BASE Child is the Child class from which the Parent class needs to be retrieved.
 -- @return #BASE
 function BASE:Inherited( Child )
@@ -122,7 +123,11 @@ function BASE:GetClassID()
   return self.ClassID
 end
 
-
+--- Set a new listener for the class.
+-- @param self
+-- @param DCSTypes#Event Event
+-- @param #function EventFunction
+-- @return #BASE
 function BASE:AddEvent( Event, EventFunction )
 	self:F( Event )
 
@@ -134,7 +139,9 @@ function BASE:AddEvent( Event, EventFunction )
 	return self
 end
 
-
+--- Enable the event listeners for the class.
+-- @param #BASE self
+-- @return #BASE
 function BASE:EnableEvents()
 	self:F( #self.Events )
 
@@ -147,6 +154,10 @@ function BASE:EnableEvents()
 	return self
 end
 
+
+--- Disable the event listeners for the class.
+-- @param #BASE self
+-- @return #BASE
 function BASE:DisableEvents()
 	self:F()
   
@@ -198,7 +209,13 @@ local BaseEventCodes = {
 --   weapon = Weapon
 -- }
 
-
+--- Creation of a Birth Event.
+-- @param #BASE self
+-- @param DCSTypes#Time EventTime The time stamp of the event.
+-- @param DCSObject#Object Initiator The initiating object of the event.
+-- @param #string IniUnitName The initiating unit name.
+-- @param place
+-- @param subplace
 function BASE:CreateEventBirth( EventTime, Initiator, IniUnitName, place, subplace )
 	self:F( { EventTime, Initiator, IniUnitName, place, subplace } )
 
@@ -214,6 +231,10 @@ function BASE:CreateEventBirth( EventTime, Initiator, IniUnitName, place, subpla
 	world.onEvent( Event )
 end
 
+--- Creation of a Crash Event.
+-- @param #BASE self
+-- @param DCSTypes#Time EventTime The time stamp of the event.
+-- @param DCSObject#Object Initiator The initiating object of the event.
 function BASE:CreateEventCrash( EventTime, Initiator )
 	self:F( { EventTime, Initiator } )
 
@@ -225,7 +246,11 @@ function BASE:CreateEventCrash( EventTime, Initiator )
 
 	world.onEvent( Event )
 end
-												
+
+-- TODO: Complete DCSTypes#Event structure.                       
+--- The main event handling function... This function captures all events generated for the class.
+-- @param #BASE self
+-- @param DCSTypes#Event event
 function BASE:onEvent(event)
 
 	--env.info( 'onEvent Table self = ' .. tostring(self) )
@@ -250,7 +275,6 @@ function BASE:onEvent(event)
 			end
 		end
 	end
-
 end
 
 -- Trace section
@@ -258,6 +282,9 @@ end
 -- Log a trace (only shown when trace is on)
 -- TODO: Make trace function using variable parameters.
 
+--- Trace a function call. Must be at the beginning of the function logic.
+-- @param #BASE self
+-- @param Arguments A #table or any field.
 function BASE:F( Arguments )
 
   if _TraceOn and _TraceClass[self.ClassName] then
@@ -279,6 +306,9 @@ function BASE:F( Arguments )
   end
 end
 
+--- Trace a function call level 2. Must be at the beginning of the function logic.
+-- @param #BASE self
+-- @param Arguments A #table or any field.
 function BASE:F2( Arguments )
 
   if _TraceLevel >= 2 then
@@ -287,6 +317,9 @@ function BASE:F2( Arguments )
   
 end
 
+--- Trace a function call level 3. Must be at the beginning of the function logic.
+-- @param #BASE self
+-- @param Arguments A #table or any field.
 function BASE:F3( Arguments )
 
   if _TraceLevel >= 3 then
@@ -295,6 +328,9 @@ function BASE:F3( Arguments )
   
 end
 
+--- Trace a function logic. Can be anywhere within the function logic.
+-- @param #BASE self
+-- @param Arguments A #table or any field.
 function BASE:T( Arguments )
 
 	if _TraceOn and _TraceClass[self.ClassName] then
@@ -316,6 +352,9 @@ function BASE:T( Arguments )
 	end
 end
 
+--- Trace a function logic level 2. Can be anywhere within the function logic.
+-- @param #BASE self
+-- @param Arguments A #table or any field.
 function BASE:T2( Arguments )
 
   if _TraceLevel >= 2 then
@@ -324,6 +363,9 @@ function BASE:T2( Arguments )
   
 end
 
+--- Trace a function logic level 3. Can be anywhere within the function logic.
+-- @param #BASE self
+-- @param Arguments A #table or any field.
 function BASE:T3( Arguments )
 
   if _TraceLevel >= 3 then
@@ -332,9 +374,9 @@ function BASE:T3( Arguments )
   
 end
 
-
+--- Log an exception which will be traced always. Can be anywhere within the function logic.
-
+-- @param #BASE self
--- Log an exception
+-- @param Arguments A #table or any field.
 function BASE:E( Arguments )
 
 	local DebugInfoCurrent = debug.getinfo( 2, "nl" )

Moose/Client.lua

@@ -1,4 +1,6 @@
---- CLIENT Classes
+--- The CLIENT models client units in multi player missions.
+-- Clients are those groups defined within the Mission Editor that have the skillset defined as "Client" or "Player".
+-- Note that clients are NOT the same as groups, they are NOT necessarily alive. 
 -- @module Client
 -- @author FlightControl
 
@@ -7,8 +9,6 @@ Include.File( "Base" )
 Include.File( "Cargo" )
 Include.File( "Message" )
 
---- Clients are those Groups defined within the Mission Editor that have the skillset defined as "Client" or "Player".
--- These clients are defined within the Mission Orchestration Framework (MOF)
 
 --- The CLIENT class
 -- @type CLIENT
@@ -58,8 +58,30 @@ function CLIENT:New( ClientName, ClientBriefing )
 	return self
 end
 
+--- Transport defines that the Client is a Transport. Transports show cargo.
+-- @param #CLIENT self
+-- @return #CLIENT
+function CLIENT:Transport()
+  self:F()
+
+  self.ClientTransport = true
+  return self
+end
+
+--- AddBriefing adds a briefing to a CLIENT when a player joins a mission.
+-- @param #CLIENT self
+-- @param #string ClientBriefing is the text defining the Mission briefing.
+-- @return #CLIENT
+function CLIENT:AddBriefing( ClientBriefing )
+  self:F()
+  self.ClientBriefing = ClientBriefing
+  return self
+end
+
+
 --- Resets a CLIENT.
--- @param string ClientName Name of the Group as defined within the Mission Editor. The Group must have a Unit with the type Client.
+-- @param #CLIENT self
+-- @param #string ClientName Name of the Group as defined within the Mission Editor. The Group must have a Unit with the type Client.
 function CLIENT:Reset( ClientName )
 	self:F()
 	self._Menus = {}
@@ -68,12 +90,13 @@ end
 --- Checks for a client alive event and calls a function on a continuous basis.
 -- @param #CLIENT self
 -- @param #function CallBack Function.
+-- @return #CLIENT
 function CLIENT:Alive( CallBack )
   self:F()
   
   self.ClientAlive2 = false
   self.ClientCallBack = CallBack
-  self.AliveCheckFunction = routines.scheduleFunction( self._AliveCheckCallBack, { self }, timer.getTime() + 1, 5 )
+  self.AliveCheckScheduler = routines.scheduleFunction( self._AliveCheckScheduler, { self }, timer.getTime() + 1, 5 )
 
   return self
 end
@@ -97,7 +120,7 @@ end
 
 
 --- @param #CLIENT self
-function CLIENT:_AliveCheckCallBack()
+function CLIENT:_AliveCheckScheduler()
   self:F( { self.ClientName, self.ClientAlive2 } )
 
   if self:IsAlive() then
@@ -115,6 +138,7 @@ end
 
 --- Return the DCSGroup of a Client.
 -- This function is modified to deal with a couple of bugs in DCS 1.5.3
+-- @param #CLIENT self
 -- @return DCSGroup#Group
 function CLIENT:GetDCSGroup()
   self:F3()
@@ -185,9 +209,12 @@ function CLIENT:GetDCSGroup()
 end 
 
 
+-- TODO: Check DCSTypes#Group.ID
+--- Get the group ID of the client.
+-- @param #CLIENT self
+-- @return DCSTypes#Group.ID
 function CLIENT:GetClientGroupID()
 
-  
   if not self.ClientGroupID then
     local ClientGroup = self:GetDCSGroup()
     if ClientGroup and ClientGroup:isExist() then
@@ -202,6 +229,9 @@ function CLIENT:GetClientGroupID()
 end
 
 
+--- Get the name of the group of the client.
+-- @param #CLIENT self
+-- @return #string
 function CLIENT:GetClientGroupName()
 
   if not self.ClientGroupName then
@@ -217,7 +247,8 @@ function CLIENT:GetClientGroupName()
 	return self.ClientGroupName
 end
 
---- Returns the Unit of the @{CLIENT}.
+--- Returns the UNIT of the CLIENT.
+-- @param #CLIENT self
 -- @return Unit#UNIT
 function CLIENT:GetClientGroupUnit()
 	self:F()
@@ -231,8 +262,9 @@ function CLIENT:GetClientGroupUnit()
 	end
 end
 
---- Returns the DCSUnit of the @{CLIENT}.
+--- Returns the DCSUnit of the CLIENT.
--- @return DCSUnit
+-- @param #CLIENT self
+-- @return DCSTypes#Unit
 function CLIENT:GetClientGroupDCSUnit()
 	self:F2()
 
@@ -245,13 +277,15 @@ function CLIENT:GetClientGroupDCSUnit()
   end
 end
 
+-- TODO what is this??? check. possible double function.
 function CLIENT:GetUnit()
 	self:F()
 	
 	return UNIT:New( self:GetClientGroupDCSUnit() )
 end
 
---- Returns the Point of the @{CLIENT}.
+--- Returns the position of the CLIENT in @{DCSTypes#Vec2} format..
+-- @param #CLIENT self
 -- @return DCSTypes#Vec2
 function CLIENT:GetPointVec2()
 	self:F()
@@ -273,8 +307,9 @@ function CLIENT:GetPointVec2()
 end 
 
 
---- Returns the Position of the @{CLIENT}.
+--- Returns the position of the CLIENT in @{DCSTypes#Vec3} format.
--- @return DCSTypes#Position
+-- @param #CLIENT self
+-- @return DCSTypes#Vec3
 function CLIENT:ClientPosition()
 	self:F()
 
@@ -289,7 +324,8 @@ function CLIENT:ClientPosition()
 	return nil
 end 
 
---- Returns the altitude of the @{CLIENT}.
+--- Returns the altitude of the CLIENT.
+-- @param #CLIENT self
 -- @return DCSTypes#Distance
 function CLIENT:GetAltitude()
 	self:F()
@@ -307,33 +343,17 @@ function CLIENT:GetAltitude()
 end 
 
 
---- Transport defines that the Client is a Transport.
+--- Evaluates if the CLIENT is a transport.
--- @return CLIENT
+-- @param #CLIENT self
-function CLIENT:Transport()
+-- @return #boolean true is a transport.
-	self:F()
-
-	self.ClientTransport = true
-	return self
-end
-
---- AddBriefing adds a briefing to a Client when a Player joins a Mission.
--- @param string ClientBriefing is the text defining the Mission briefing.
--- @return CLIENT
-function CLIENT:AddBriefing( ClientBriefing )
-	self:F()
-	self.ClientBriefing = ClientBriefing
-	return self
-end
-
---- IsTransport returns if a Client is a transport.
--- @return bool
 function CLIENT:IsTransport()
 	self:F()
 	return self.ClientTransport
 end
 
---- ShowCargo shows the @{CARGO} within the CLIENT to the Player.
+--- Shows the @{Cargo#CARGO} contained within the CLIENT to the player as a message.
--- The @{CARGO} is shown throught the MESSAGE system of DCS World.
+-- The @{Cargo#CARGO} is shown using the @{Message#MESSAGE} distribution system.
+-- @param #CLIENT self
 function CLIENT:ShowCargo()
 	self:F()
 
@@ -353,18 +373,20 @@ function CLIENT:ShowCargo()
 
 end
 
---- SwitchMessages is a local function called by the DCS World Menu system to switch off messages.
+-- TODO (1) I urgently need to revise this.
+--- A local function called by the DCS World Menu system to switch off messages.
 function CLIENT.SwitchMessages( PrmTable )
 	PrmTable[1].MessageSwitch = PrmTable[2]
 end
 
---- Message is the key Message driver for the CLIENT class.
+--- The main message driver for the CLIENT.
 -- This function displays various messages to the Player logged into the CLIENT through the DCS World Messaging system.
--- @param string Message is the text describing the message.
+-- @param #CLIENT self
--- @param number MessageDuration is the duration in seconds that the Message should be displayed.
+-- @param #string Message is the text describing the message.
--- @param string MessageId is a text identifying the Message in the MessageQueue. The Message system overwrites Messages with the same MessageId
+-- @param #number MessageDuration is the duration in seconds that the Message should be displayed.
--- @param string MessageCategory is the category of the message (the title).
+-- @param #string MessageId is a text identifying the Message in the MessageQueue. The Message system overwrites Messages with the same MessageId
--- @param number MessageInterval is the interval in seconds between the display of the Message when the CLIENT is in the air.
+-- @param #string MessageCategory is the category of the message (the title).
+-- @param #number MessageInterval is the interval in seconds between the display of the @{Message#MESSAGE} when the CLIENT is in the air.
 function CLIENT:Message( Message, MessageDuration, MessageId, MessageCategory, MessageInterval )
 	self:F()