initial doxygen comments and minor cleanup

src/blackcore/simulator.cpp

@@ -43,7 +43,7 @@ namespace BlackCore {
 		ISimulator *result = NULL;
 
 		getDriverVersionMajor driverVersionMajor;
-		getDriverVersionMinor driverVersionMinor;
+		//getDriverVersionMinor driverVersionMinor;
 		createISimulatorInstance createDriver;
 
 		switch (sim)

src/blackcore/simulator.h

@@ -6,17 +6,21 @@
 #ifndef SIMULATOR_H
 #define SIMULATOR_H
 
-#include <QString>
-#include <functional>
-
 #include "blackcore/sim_callbacks.h"
 #include "blackcore/vector_geo.h"
 #include "blackcore/vector_3d.h"
 
+#include <QString>
+#include <functional>
+
 #define SHARED_LIBRARY_NAME_FS9 "bb_driver_fs9"
 #define SHARED_LIBRARY_NAME_FSX "bb_driver_fsx"
 #define SHARED_LIBRARY_NAME_XPLANE "bb_driver_xplane"
 
+/*!
+ * \file Simulator driver interface.
+ */
+
 namespace BlackMisc {
 
     class IContext;
@@ -25,144 +29,193 @@ namespace BlackMisc {
 
 namespace BlackCore {
 
+    /*!
+     * A struct to hold data about an aircraft model and repaint.
+     */
     class CPlaneModel
     {
     public:
-        QString name;
+        QString name;           //!< full name of the aircraft model, arbitrary string (hopefully unique)
-        QString typeCode;
+        QString typeCode;       //!< ICAO aircraft type code
-        QString airlineCode;
+        QString airlineCode;    //!< ICAO air operator code
     };
 
+    /*!
+     * A struct for passing around the physical state of an aircraft.
+     */
     class CPhysicalState
     {
     public:
+        //! Constructor, initialize to zero.
         CPhysicalState() : headingDegrees(0), pitchDegrees(0), bankDegrees(0), groundSpeedKnots(0)
         {}
-        CVectorGeo position;
+        CVectorGeo position;    //!< geographical position
-        float headingDegrees;
+        float headingDegrees;   //!< heading in degrees
-        float pitchDegrees;
+        float pitchDegrees;     //!< pitch in degrees
-        float bankDegrees;
+        float bankDegrees;      //!< bank in degrees
-        float groundSpeedKnots;
+        float groundSpeedKnots; //!< ground speed in knots
-        CVector3D trueSpeedMetersPerSec;
+        CVector3D trueSpeedMetersPerSec;    //!< needed by FSX
     };
 
+    /*!
+     * A struct for passing around the avionics state of an aircraft.
+     */
     class CAvionicsState
     {
+        //! Constructor, initialize to zero.
         CAvionicsState() : squawkCode(0), squawkModeC(false), squawkIdent(false),
             com1FreqHz(0), com2FreqHz(0)
         {}
-        qint16 squawkCode;
+        qint16 squawkCode;  //!< decimal squawk code
-        bool squawkModeC;
+        bool squawkModeC;   //!< true if squawking mode C
-        bool squawkIdent;
+        bool squawkIdent;   //!< true if squawking ident
-        qint32 com1FreqHz;
+        qint32 com1FreqHz;  //!< COM1 radio frequency in Hz
-        qint32 com2FreqHz;
+        qint32 com2FreqHz;  //!< COM2 radio frequency in Hz
     };
 
+    /*!
+     * A struct for passing around the animation state of an aircraft.
+     */
     class CAnimationState
     {
     public:
+        //! Constructor, initialize to zero.
         CAnimationState() : gearPercent(0), flapsPercent(0), landingLights(false),
             taxiLights(false), navLights(false), strobeLights(false), beaconLights(false)
         {}
-        qint8 gearPercent;
+        qint8 gearPercent;  //!< 0 = retracted, 100 = extended
-        qint8 flapsPercent;
+        qint8 flapsPercent; //!< 0 = ratracted, 100 = extended
-        bool landingLights;
+        bool landingLights; //!< true if landing lights on
-        bool taxiLights;
+        bool taxiLights;    //!< true if taxi lights on
-        bool navLights;
+        bool navLights;     //!< true if nav lights on
-        bool strobeLights;
+        bool strobeLights;  //!< true if strobe lights on
-        bool beaconLights;
+        bool beaconLights;  //!< true if beacon lights on
     };
 
+    //! A callback that is called when the simulator is started.
     typedef std::tr1::function<void(const bool status)> cbSimStarted;
-    typedef std::tr1::function<void(const CAvionicsState &state)> cbChangedAvionicsState;
-    typedef std::tr1::function<void(const CAnimationState &state)> cbChangedAnimationState;
-    typedef std::tr1::function<void(const CPlaneModel &model)> cbChangedModel;
-    typedef std::tr1::function<void(const QString &message)> cbSendTextMessage;
 
+    //! A callback that is called when the user's plane changes its avionics state.
+    typedef std::tr1::function<void(const CAvionicsState &state)> cbChangedAvionicsState;
+
+    //! A callback that is called when the user's plane changes its animation state.
+    typedef std::tr1::function<void(const CAnimationState &state)> cbChangedAnimationState;
+
+    //! A callback that is called when the user's plane changes its model.
+    typedef std::tr1::function<void(const CPlaneModel &model)> cbChangedModel;
+
+    /*!
+     * The interface that is implemented by each simulator driver.
+     *
+     * Simulator drivers are responsible for communicating with the simulator on the user's
+     * computer and keeping it in sync with the client.
+     */
     class ISimulator
 	{
 	public:
-
+		// Version of the driver interface. To increment when the interface change.
-		/// Version of the driver interface. To increment when the interface change.
 		static const quint32         InterfaceVersionMajor;
 		static const quint32         InterfaceVersionMinor;
 
+        //! Enumeration to describe which simulator is desired.
 		enum ESimulator {
-            FS9 = 0,
+            FS9 = 0,    //!< Microsoft Flight Simulator 9
-			FSX,
+			FSX,        //!< Microsoft Flight Simulator 10
-			XPLANE,
+			XPLANE,     //!< X-Plane
         };
 
+        //! Constructor.
 		ISimulator() {}
+
+        //! Destructor.
 		virtual ~ISimulator() {}
 
+        //! Provide the driver with a pointer to the global context.
 		virtual void setLibraryContext(BlackMisc::IContext *context);
 
+        //! Factory method.
 		static ISimulator *createDriver(ESimulator sim);
 	
-		////////////////////////////////
+        //! Initialize the driver.
-		// Global section
-		////////////////////////////////
-
 		virtual int init() = 0;
 
+        //! Connect to the simulator.
 		virtual int connect() = 0;
 
-		// Callback when the Simulation starts
+		//! Provide a callback to be called when the simulation starts.
 		virtual void setcbSimStarted(const cbSimStarted &func);
 
+        //! Query whether the driver is connected to the simulator.
 		virtual bool isConnected() = 0;
 
+        //! If there has been an error, return the associated message.
 		virtual QString getLastErrorMessage() = 0;
 
-		////////////////////////////////
+		//! Provide a callback to be called when the user plane changes avionics state.
-		// User plane section
-		////////////////////////////////
-
-		// Callback avionics state
 		virtual void setcbChangedAvionicsState(const cbChangedAvionicsState &func);
 
-		// Callback animation state
+		//! Provide a callback to be called when the user plane changes animation state.
 		virtual void setcbChangedAnimationState(const cbChangedAnimationState &func);
 
-		// Callback, when the Aircraft is set or gets changed
+		//! Provide a callback to be called when the user plane changes model.
 		virtual void setcbChangedModel(const cbChangedModel &func);
 
-        // Not const because it may need to mutate state in order to communicate with the sim
+        //! Returns true if the user plane is in contact with the ground.
 		virtual bool isOnGround() = 0;
 
-        // This might block - use QtConcurrent::run if that is a problem
+        /*!
+         * Returns the physical state of the user plane.
+         * \warning This might block - use QtConcurrent::run if that is a problem.
+         */
         virtual CPhysicalState getPhysicalState() = 0;
 
-		////////////////////////////////
+        /*!
-		// Remote plane section
+         * Adds a plane to the simulator traffic and returns its handle.
-		////////////////////////////////
+         * \warning This might block - use QtConcurrent::run if that is a problem
-
+         */
-        // This might block - use QtConcurrent::run if that is a problem
 		virtual qint32 addPlane(const QString &callsign) = 0;
 
+        /*!
+         * Remove a plane from the simulator traffic.
+         * \param planeID a handle that was returned by addPlane().
+         */
 		virtual bool removePlane(const qint32 planeID) = 0;
 
+        /*!
+         * Set the model of an aircraft in the simulator traffic.
+         * \param planeID a handle that was returned by addPlane().
+         */
         virtual void setModel(const qint32 planeID, const CPlaneModel &model) = 0;
 
+        /*!
+         * Set the physical state of an aircraft in the simulator traffic.
+         * \param planeID a handle that was returned by addPlane().
+         */
 		virtual bool setPhysicalState(const qint32 planeID, const CPhysicalState &state) = 0;
 
+        /*!
+         * Set the animation state of an aircraft in the simulator traffic.
+         * \param planeID a handle that was returned by addPlane().
+         */
 		virtual bool setAnimationState(const qint32 planeID, const CAnimationState &state) = 0;
 
-        // Calls the supplied visitor function once for every model available in the simulator.
+        //! Calls the supplied visitor function once for every model available in the simulator.
         virtual void visitAllModels(const std::tr1::function<void(const CPlaneModel &)> &visitor) = 0;
 
-        // Fills container with all models. Works for any container that supports push_back.
+        /*!
+         * Fills container with all models.
+         * Class T must be a container of CPlaneModel objects and must support push_back.
+         */
         template <class T>
         void getAllModels(T &container) { visitAllModels(std::tr1::bind(T::push_back, container)); }
 
 	protected:
-        BlackMisc::IContext *m_libraryContext;
+        BlackMisc::IContext *m_libraryContext;              //!< The global context.
 	
-		cbSimStarted m_cbSimStarted;
+		cbSimStarted m_cbSimStarted;                        //!< Callback to call when the sim starts.
-		cbChangedAvionicsState m_cbChangedAvionicsState;
+		cbChangedAvionicsState m_cbChangedAvionicsState;    //!< Callback to call when the user plane changes avionics state.
-		cbChangedAnimationState m_cbChangedAnimationState;
+		cbChangedAnimationState m_cbChangedAnimationState;  //!< Callback to call when the user plane changes animation state.
-		cbChangedModel m_cbChangedModel;
+		cbChangedModel m_cbChangedModel;                    //!< Callback to call when the user plane changes model.
 	};
 
 } //! namespace BlackCore