FlightControl-Master/MOOSE
1
0
Fork 0
mirror of https://github.com/FlightControl-Master/MOOSE.git synced 2025-10-29 16:58:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

Revision of core classes documentation.

Browse Source
This commit is contained in:
FlightControl
2018-10-09 19:30:57 +02:00
parent e6f51af34c
commit f03a2e3657
20 changed files with 298 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
Moose Development/Moose/Core/Base.lua
View File

@@ -1,4 +1,22 @@
--- **Core** -- BASE forms **the basis of the MOOSE framework**. Each class within the MOOSE framework derives from BASE.
--- **Core** - The base class within the framework.
--
-- ===
--
-- ## Features:
--
-- * The construction and inheritance of MOOSE classes.
-- * The class naming and numbering system.
-- * The class hierarchy search system.
-- * The tracing of information or objects during mission execution for debuggin purposes.
-- * The subscription to DCS events for event handling in MOOSE objects.
-- * Object inspection.
--
-- ===
--
-- All classes within the MOOSE framework are derived from the BASE class.
-- Note: The BASE class is an abstract class and is not meant to be used directly.
--
-- ===
--
-- ### Author: **FlightControl**
-- ### Contributions:
@@ -23,24 +41,14 @@ local _ClassID = 0
-- @field ClassID The ID number of the class.
-- @field ClassNameAndID The name of the class concatenated with the ID number of the class.
--- All classes within the MOOSE framework are derived from the BASE class.
--
-- BASE provides facilities for :
--
-- * The construction and inheritance of MOOSE classes.
-- * The class naming and numbering system.
-- * The class hierarchy search system.
-- * The tracing of information or objects during mission execution for debuggin purposes.
-- * The subscription to DCS events for event handling in MOOSE objects.
--
-- Note: The BASE class is an abstract class and is not meant to be used directly.
--
-- ## 1.1) BASE constructor
--- BASE class
--
-- # 1. BASE constructor.
--
-- Any class derived from BASE, will use the @{Core.Base#BASE.New} constructor embedded in the @{Core.Base#BASE.Inherit} method.
-- See an example at the @{Core.Base#BASE.New} method how this is done.
--
-- ## 1.2) Trace information for debugging
-- # 2. Trace information for debugging.
--
-- The BASE class contains trace methods to trace progress within a mission execution of a certain object.
-- These trace methods are inherited by each MOOSE class interiting BASE, soeach object created from derived class from BASE can use the tracing methods to trace its execution.
@@ -71,7 +79,7 @@ local _ClassID = 0
--
-- Below a more detailed explanation of the different method types for tracing.
--
-- ### 1.2.1) Tracing methods categories
-- ## 2.1. Tracing methods categories.
--
-- There are basically 3 types of tracing methods available:
--
@@ -79,9 +87,9 @@ local _ClassID = 0
-- * @{#BASE.T}: Used to trace further logic within a function giving optional variables or parameters. A T is indicated at column 44 in the DCS.log file.
-- * @{#BASE.E}: Used to always trace information giving optional variables or parameters. An E is indicated at column 44 in the DCS.log file.
--
-- ### 1.2.2) Tracing levels
-- ## 2.2 Tracing levels.
--
-- There are 3 tracing levels within MOOSE.
-- There are 3 tracing levels within MOOSE.
-- These tracing levels were defined to avoid bulks of tracing to be generated by lots of objects.
--
-- As such, the F and T methods have additional variants to trace level 2 and 3 respectively:
@@ -91,7 +99,7 @@ local _ClassID = 0
-- * @{#BASE.T2}: Trace further logic within a function giving optional variables or parameters with tracing level 2.
-- * @{#BASE.T3}: Trace further logic within a function giving optional variables or parameters with tracing level 3.
--
-- ### 1.2.3) Trace activation.
-- ## 2.3. Trace activation.
--
-- Tracing can be activated in several ways:
--
@@ -101,16 +109,17 @@ local _ClassID = 0
-- * Activate only the tracing of a certain method of a certain class through the @{#BASE.TraceClassMethod}() method.
-- * Activate only the tracing of a certain level through the @{#BASE.TraceLevel}() method.
--
-- ### 1.2.4) Check if tracing is on.
-- ## 2.4. Check if tracing is on.
--
-- The method @{#BASE.IsTrace}() will validate if tracing is activated or not.
--
-- ## 1.3 DCS simulator Event Handling
--
-- # 3. DCS simulator Event Handling.
--
-- The BASE class provides methods to catch DCS Events. These are events that are triggered from within the DCS simulator,
-- and handled through lua scripting. MOOSE provides an encapsulation to handle these events more efficiently.
--
-- ### 1.3.1 Subscribe / Unsubscribe to DCS Events
-- ## 3.1. Subscribe / Unsubscribe to DCS Events.
--
-- At first, the mission designer will need to **Subscribe** to a specific DCS event for the class.
-- So, when the DCS event occurs, the class will be notified of that event.
@@ -119,7 +128,7 @@ local _ClassID = 0
-- * @{#BASE.HandleEvent}(): Subscribe to a DCS Event.
-- * @{#BASE.UnHandleEvent}(): Unsubscribe from a DCS Event.
--
-- ### 1.3.2 Event Handling of DCS Events
-- ## 3.2. Event Handling of DCS Events.
--
-- Once the class is subscribed to the event, an **Event Handling** method on the object or class needs to be written that will be called
-- when the DCS event occurs. The Event Handling method receives an @{Core.Event#EVENTDATA} structure, which contains a lot of information
@@ -154,7 +163,7 @@ local _ClassID = 0
--
-- See the @{Event} module for more information about event handling.
--
-- ## 1.4) Class identification methods
-- # 4. Class identification methods.
--
-- BASE provides methods to get more information of each object:
--
@@ -162,7 +171,7 @@ local _ClassID = 0
-- * @{#BASE.GetClassName}(): Gets the name of the object, which is the name of the class the object was instantiated from.
-- * @{#BASE.GetClassNameAndID}(): Gets the name and ID of the object.
--
-- ## 1.5) All objects derived from BASE can have "States"
-- # 5. All objects derived from BASE can have "States".
--
-- A mechanism is in place in MOOSE, that allows to let the objects administer **states**.
-- States are essentially properties of objects, which are identified by a **Key** and a **Value**.
@@ -177,7 +186,7 @@ local _ClassID = 0
-- Thus, if the state is to be set for the same object as the object for which the method is used, then provide the same
-- object name to the method.
--
-- ## 1.10) Inheritance
-- # 6. Inheritance.
--
-- The following methods are available to implement inheritance
--
@@ -186,8 +195,7 @@ local _ClassID = 0
--
-- ===
--
-- @field #BASE BASE
--
-- @field #BASE
BASE = {
ClassName = "BASE",
ClassID = 0,