From 2dc82d5227069044cb469d80b2abb5b46aa06e90 Mon Sep 17 00:00:00 2001 From: FlightControl Date: Sat, 2 Apr 2016 22:41:34 +0200 Subject: [PATCH 1/4] Updated luadoc documentation BASE CLIENT --- Moose/Base.lua | 72 ++++++++++++++++++++++++------- Moose/Client.lua | 108 ++++++++++++++++++++++++++++------------------- 2 files changed, 122 insertions(+), 58 deletions(-) diff --git a/Moose/Base.lua b/Moose/Base.lua index 6e9a563ee..a8efec0fc 100644 --- a/Moose/Base.lua +++ b/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 --- @return #BASE +-- @param #BASE self +-- @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. --- @return Child +-- @param #BASE Parent is the Parent class that the Child inherits from. +-- @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 +--- Log an exception which will be traced always. Can be anywhere within the function logic. +-- @param #BASE self +-- @param Arguments A #table or any field. function BASE:E( Arguments ) local DebugInfoCurrent = debug.getinfo( 2, "nl" ) diff --git a/Moose/Client.lua b/Moose/Client.lua index d91618860..b18c3085b 100644 --- a/Moose/Client.lua +++ b/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}. --- @return DCSUnit +--- Returns the DCSUnit of the CLIENT. +-- @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}. --- @return DCSTypes#Position +--- Returns the position of the CLIENT in @{DCSTypes#Vec3} format. +-- @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. --- @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 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 +--- Evaluates if the CLIENT is a transport. +-- @param #CLIENT self +-- @return #boolean true is a transport. function CLIENT:IsTransport() self:F() return self.ClientTransport end ---- ShowCargo shows the @{CARGO} within the CLIENT to the Player. --- The @{CARGO} is shown throught the MESSAGE system of DCS World. +--- Shows the @{Cargo#CARGO} contained within the CLIENT to the player as a message. +-- 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 number MessageDuration is the duration in seconds that the Message should be displayed. --- @param string MessageId is a text identifying the Message in the MessageQueue. The Message system overwrites Messages with the same MessageId --- @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 when the CLIENT is in the air. +-- @param #CLIENT self +-- @param #string Message is the text describing the message. +-- @param #number MessageDuration is the duration in seconds that the Message should be displayed. +-- @param #string MessageId is a text identifying the Message in the MessageQueue. The Message system overwrites Messages with the same MessageId +-- @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() From 9da2f56d37e697ca4908431d3ec08aba7bdee6c3 Mon Sep 17 00:00:00 2001 From: FlightControl Date: Sat, 2 Apr 2016 23:06:26 +0200 Subject: [PATCH 2/4] Updated CLEANUP luadoc documentation. --- Documentation/Base.html | 144 ++++++---- Documentation/CARGO.html | 3 +- Documentation/CLEANUP.html | 126 ++++----- Documentation/Client.html | 354 +++++++++++++++++------- Documentation/DCSAirbase.html | 3 +- Documentation/DCSCoalitionObject.html | 3 +- Documentation/DCSController.html | 3 +- Documentation/DCSGroup.html | 3 +- Documentation/DCSObject.html | 3 +- Documentation/DCSTask.html | 119 ++++++++ Documentation/DCSTypes.html | 3 +- Documentation/DCSUnit.html | 3 +- Documentation/DCStimer.html | 3 +- Documentation/DEPLOYTASK.html | 3 +- Documentation/DESTROYBASETASK.html | 3 +- Documentation/DESTROYGROUPSTASK.html | 3 +- Documentation/DESTROYRADARSTASK.html | 3 +- Documentation/DESTROYUNITTYPESTASK.html | 3 +- Documentation/Database.html | 3 +- Documentation/Escort.html | 3 +- Documentation/GOHOMETASK.html | 3 +- Documentation/Group.html | 3 +- Documentation/MISSION.html | 3 +- Documentation/MOVEMENT.html | 3 +- Documentation/Menu.html | 3 +- Documentation/Message.html | 3 +- Documentation/NOTASK.html | 3 +- Documentation/PICKUPTASK.html | 3 +- Documentation/ROUTETASK.html | 3 +- Documentation/STAGE.html | 3 +- Documentation/Sead.html | 3 +- Documentation/Spawn.html | 3 +- Documentation/StaticObject.html | 3 +- Documentation/TASK.html | 3 +- Documentation/Unit.html | 3 +- Documentation/Zone.html | 3 +- Documentation/env.html | 3 +- Documentation/index.html | 17 +- Documentation/land.html | 3 +- Documentation/routines.html | 3 +- Moose/CleanUp.lua | 55 ++-- 41 files changed, 637 insertions(+), 283 deletions(-) create mode 100644 Documentation/DCSTask.html diff --git a/Documentation/Base.html b/Documentation/Base.html index dd64bba02..88242a92c 100644 --- a/Documentation/Base.html +++ b/Documentation/Base.html @@ -19,13 +19,14 @@