doxygen comments for all non-private members of INetwork, refs #91

src/blackcore/network.h

@@ -52,14 +52,19 @@ namespace BlackCore
 
     protected:
         /*!
-         * \brief Constructor
+         * Constructor
-         * \param parent
          */
         INetwork(QObject *parent = nullptr) : QObject(parent) {}
 
     public:
+        /*!
+         * Destructor.
+         */
         virtual ~INetwork() {}
 
+        /*!
+         * Flags for capabilities bitfield.
+         */
         enum
         {
             AcceptsAtisResponses        = 1 << 0,
@@ -67,21 +72,30 @@ namespace BlackCore
             SupportsModelDescriptions   = 1 << 2
         };
 
+        /*!
+         * Login modes
+         */
         enum LoginMode
         {
-            LoginNormal = 0,
+            LoginNormal = 0,    //!< Normal login
-            LoginAsObserver,
+            LoginAsObserver,    //!< Login as observer
-            LoginStealth
+            LoginStealth        //!< Login stealth mode
         };
 
+        /*!
+         * Status of the connection.
+         */
         enum ConnectionStatus
         {
-            Disconnected = 0,
+            Disconnected = 0,   //!< Not connected
-            DisconnectedError,
+            DisconnectedError,  //!< Disconnected due to socket error
-            Connecting,
+            Connecting,         //!< Connection initiated but not established
-            Connected
+            Connected           //!< Connection established
         };
 
+        /*!
+         * Convert a ConnectionStatus to a string.
+         */
         static QString connectionStatusToString(ConnectionStatus status)
         {
             int index = staticMetaObject.indexOfEnumerator("ConnectionStatus");
@@ -89,85 +103,340 @@ namespace BlackCore
             return metaEnum.valueToKey(status);
         }
 
+        /*!
+         * Returns true if the given ConnectionStatus represents an error state.
+         */
         static bool isErrorStatus(ConnectionStatus status)
         {
             return status == DisconnectedError;
         }
 
+        /*!
+         * Returns true if the current ConnectionStatus is a connected state.
+         */
         virtual bool isConnected() const = 0;
 
     public slots:
-        // Network
+        ////////////////////////////////////////////////////////////////
+        //! \name Network slots
+        //! @{
+        ////////////////////////////////////////////////////////////////
+
+        /*!
+         * Set the server which will be connected to.
+         * \pre Network must be disconnected when calling this function.
+         */
         virtual void presetServer(const BlackMisc::Network::CServer &server) = 0;
+
+        /*!
+         * Set our own callsign before connecting.
+         * \pre Network must be disconnected when calling this function.
+         */
         virtual void presetCallsign(const BlackMisc::Aviation::CCallsign &callsign) = 0;
+
+        /*!
+         * Set our own aircraft ICAO codes before connecting.
+         * \pre Network must be disconnected when calling this function.
+         */
         virtual void presetIcaoCodes(const BlackMisc::Aviation::CAircraftIcao &icao) = 0;
+
+        /*!
+         * Select a login mode before connecting.
+         * \pre Network must be disconnected when calling this function.
+         */
         virtual void presetLoginMode(LoginMode mode) = 0;
+
+        /*!
+         * Initiate a connection to the network server.
+         * \pre Network must be disconnected when calling this function.
+         * \post Connection status changes from Disconnected to either Connecting or DisconnectedError.
+         */
         virtual void initiateConnection() = 0;
+
+        /*!
+         * Ask the connection to the network server to terminate itself.
+         * \pre It is not legal to call this function when already disconnected.
+         * \post Connection status changes to Disconnected, but maybe not immediately.
+         */
         virtual void terminateConnection() = 0;
+
+        /*!
+         * Send a ping message to a user with a specific callsign.
+         * \pre Network must be connected when calling this function.
+         * \sa pongReceived
+         */
         virtual void sendPing(const BlackMisc::Aviation::CCallsign &callsign) = 0;
 
+        /*!
+         * Send a message querying the real name of the user with a specific callsign.
+         * \pre Network must be connected when calling this function.
+         * \sa realNameReplyReceived
+         */
         virtual void sendRealNameQuery(const BlackMisc::Aviation::CCallsign &callsign) = 0;
+
+        /*!
+         * Send a message querying our own IP address as reported by the server.
+         * \pre Network must be connected when calling this function.
+         * \sa ipReplyReceived
+         */
         virtual void sendIpQuery() = 0;
+
+        /*!
+         * Send a message querying which server the user with a specific callsign is connected to.
+         * \pre Network must be connected when calling this function.
+         * \sa serverReplyReceived
+         */
         virtual void sendServerQuery(const BlackMisc::Aviation::CCallsign &callsign) = 0;
 
-        // Text messages
+        /*!
+         * Send one or more text messages.
+         * \pre Network must be connected when calling this function.
+         */
         virtual void sendTextMessages(const BlackMisc::Network::CTextMessageList &messages) = 0;
 
-        // ATC
+        //! @}
+        ////////////////////////////////////////////////////////////////
+        //! \name ATC slots
+        //! @{
+        ////////////////////////////////////////////////////////////////
+
+        /*!
+         * Send a message querying whether or not the user with a specific callsign is an ATC station.
+         * \pre Network must be connected when calling this function.
+         * \sa atcReplyReceived
+         */
         virtual void sendAtcQuery(const BlackMisc::Aviation::CCallsign &callsign) = 0;
+
+        /*!
+         * Send a message querying the ATIS for the ATC station with a specific callsign.
+         * \pre Network must be connected when calling this function.
+         * \sa atisReplyReceived
+         * \sa atisVoiceRoomReplyReceived
+         * \sa atisLogoffTimeReplyReceived
+         */
         virtual void sendAtisQuery(const BlackMisc::Aviation::CCallsign &callsign) = 0;
 
-        // Aircraft
+        // TODO virtual void sendFlightPlan(...) = 0;
+
+        //! @}
+        ////////////////////////////////////////////////////////////////
+        //! \name Aircraft slots
+        //! @{
+        ////////////////////////////////////////////////////////////////
+
+        /*!
+         * Send a message querying the capabilities of the client software of the user with a specific callsign.
+         * \pre Network must be connected when calling this function.
+         * \sa capabilitiesReplyReceived
+         */
         virtual void sendCapabilitiesQuery(const BlackMisc::Aviation::CCallsign &callsign) = 0;
+
+        /*!
+         * Send a message querying the ICAO codes of the aircraft of the user with a specific callsign.
+         * \pre Network must be connected when calling this function.
+         * \sa icaoCodesReplyReceived
+         */
         virtual void sendIcaoCodesQuery(const BlackMisc::Aviation::CCallsign &callsign) = 0;
+
+        /*!
+         * Send a message querying the COM frequency of the user with a specific callsign.
+         * \pre Network must be connected when calling this function.
+         * \sa frequencyReplyReceived
+         */
         virtual void sendFrequencyQuery(const BlackMisc::Aviation::CCallsign &callsign) = 0;
+
+        /*!
+         * Set our own aircraft data.
+         * \param aircraft Only the situation and avionics parts are used. Callsign, user, and ICAO code parts are ignored.
+         */
         virtual void setOwnAircraft(const BlackMisc::Aviation::CAircraft &aircraft) = 0;
+
+        /*!
+         * Set the position and altitude of our own aircraft.
+         */
         virtual void setOwnAircraftPosition(const BlackMisc::Geo::CCoordinateGeodetic &position, const BlackMisc::Aviation::CAltitude &altitude) = 0;
+
+        /*!
+         * Set the position, altitude, orientation, and miscellaneous state of our own aircraft.
+         */
         virtual void setOwnAircraftSituation(const BlackMisc::Aviation::CAircraftSituation &situation) = 0;
+
+        /*!
+         * Set the COM frequencies and transponder code and mode of our own aircraft.
+         */
         virtual void setOwnAircraftAvionics(const BlackMisc::Aviation::CComSystem &com1, const BlackMisc::Aviation::CComSystem &com2,
                                             const BlackMisc::Aviation::CTransponder &transponder) = 0;
 
-        // Weather / flight plan
+        //! @}
+        ////////////////////////////////////////////////////////////////
+        //! \name Weather slots
+        //! @{
+        ////////////////////////////////////////////////////////////////
+
+        /*!
+         * Send a message querying the METAR for the airport with a specific ICAO code.
+         * \pre Network must be connected when calling this function.
+         * \sa metarReplyReceived
+         */
         virtual void sendMetarQuery(const QString &airportICAO) = 0;
+
+        /*!
+         * Send a message querying the weather data for the airport with a specific ICAO code.
+         * \pre Network must be connected when calling this function.
+         * \sa temperatureDataReplyReceived
+         * \sa windDataReplyReceived
+         * \sa cloudDataReplyReceived
+         */
         virtual void sendWeatherDataQuery(const QString &airportICAO) = 0;
-        // TODO virtual void sendFlightPlan(...) = 0;
 
     signals:
-        // ATC
+        //! @}
+        ////////////////////////////////////////////////////////////////
+        //! \name ATC signals
+        //! @{
+        ////////////////////////////////////////////////////////////////
+
+        /*!
+         * We received a notification of the state of an ATC station on the network.
+         */
         void atcPositionUpdate(const BlackMisc::Aviation::CCallsign &callsign, const BlackMisc::PhysicalQuantities::CFrequency &freq,
                                const BlackMisc::Geo::CCoordinateGeodetic &pos, const BlackMisc::PhysicalQuantities::CLength &range);
+
+        /*!
+         * We received a notification that an ATC station has disconnected from the network.
+         */
         void atcDisconnected(const BlackMisc::Aviation::CCallsign &callsign);
+
+        /*!
+         * We received a reply to one of our queries.
+         * \sa sendAtcQuery
+         */
         void atcReplyReceived(const BlackMisc::Aviation::CCallsign &callsign, bool isATC);
+
+        /*!
+         * We received a reply to one of our ATIS queries.
+         * \sa sendAtisQuery
+         */
         void atisReplyReceived(const BlackMisc::Aviation::CCallsign &callsign, const BlackMisc::Aviation::CInformationMessage &atis);
+
+        /*!
+         * We received a reply to one of our ATIS queries, containing the controller's voice room URL.
+         * \sa sendAtisQuery
+         */
         void atisVoiceRoomReplyReceived(const BlackMisc::Aviation::CCallsign &callsign, const QString &url);
+
+        /*!
+         * We received a reply to one of our ATIS queries, containing the controller's planned logoff time.
+         * \sa sendAtisQuery
+         */
         void atisLogoffTimeReplyReceived(const BlackMisc::Aviation::CCallsign &callsign, const QString &zuluTime);
+
+        /*!
+         * We received a reply to one of our METAR queries.
+         * \sa sendMetarQuery
+         */
         void metarReplyReceived(const QString &data);
 
-        // Aircraft
+        //! @}
+        ////////////////////////////////////////////////////////////////
+        //! \name Aircraft signals
+        //! @{
+        ////////////////////////////////////////////////////////////////
+
+        /*!
+         * We received a notification that a pilot has disconnected from the network.
+         */
         void pilotDisconnected(const BlackMisc::Aviation::CCallsign &callsign);
+
+        /*!
+         * We received a reply to one of our queries.
+         * \sa sendIcaoCodesQuery
+         */
         void icaoCodesReplyReceived(const BlackMisc::Aviation::CCallsign &callsign, const BlackMisc::Aviation::CAircraftIcao &icao);
+
+        /*!
+         * We received a notification of the state of another aircraft on the network.
+         */
         void aircraftPositionUpdate(const BlackMisc::Aviation::CCallsign &callsign, const BlackMisc::Aviation::CAircraftSituation &situation,
                                     const BlackMisc::Aviation::CTransponder &transponder);
-        // TODO void aircraftInterimPositionUpdate(...);
+
+        /*!
+         * We received a reply to one of our queries.
+         * \sa sendFrequencyQuery
+         */
         void frequencyReplyReceived(const BlackMisc::Aviation::CCallsign &callsign, const BlackMisc::PhysicalQuantities::CFrequency &freq);
 
-        // Connection / Network in general
+        // TODO void aircraftInterimPositionUpdate(...);
+
+        //! @}
+        ////////////////////////////////////////////////////////////////
+        //! \name Network signals
+        //! @{
+        ////////////////////////////////////////////////////////////////
+
+        /*!
+         * We sent a message about the status of the network connection, for the attention of the user.
+         */
         void statusMessage(const BlackMisc::CStatusMessage &message);
+
+        /*!
+         * We were kicked from the network. (A connectionStatusChanged signal will also be sent.)
+         */
         void kicked(const QString &msg);
+
+        /*!
+         * The status of our connection has changed.
+         */
         void connectionStatusChanged(ConnectionStatus oldStatus, ConnectionStatus newStatus);
+
+        /*!
+         * We received a reply to one of our pings.
+         * \sa sendPing
+         */
         void pongReceived(const BlackMisc::Aviation::CCallsign &callsign, const BlackMisc::PhysicalQuantities::CTime &elapsedTime);
+
+        /*!
+         * We received a reply to one of our queries.
+         * \param flags A combination of capabilities flags.
+         * \sa sendCapabilitiesQuery
+         */
         void capabilitiesReplyReceived(const BlackMisc::Aviation::CCallsign &callsign, quint32 flags);
+
+        /*!
+         * We received a reply to one of our queries.
+         * \param ip Our IP address, as seen by the server.
+         * \sa sendIpQuery
+         */
         void ipReplyReceived(const QString &ip);
+
+        /*!
+         * We received a reply to one of our queries.
+         * \sa sendServerQuery
+         */
         void serverReplyReceived(const BlackMisc::Aviation::CCallsign &callsign, const QString &hostname);
 
+        /*!
+         * We received a reply to one of our queries.
+         * \sa sendRealNameQuery
+         */
         void realNameReplyReceived(const BlackMisc::Aviation::CCallsign &callsign, const QString &realname);
-        // Text messages
+
+        /*!
+         * We received one or more text messages from another user.
+         */
         void textMessagesReceived(const BlackMisc::Network::CTextMessageList &messages);
 
-        // Weather
+        //! @}
+        ////////////////////////////////////////////////////////////////
+        //! \name Weather signals
+        //! @{
+        ////////////////////////////////////////////////////////////////
+
         // TODO void temperatureDataReplyReceived(...);
         // TODO void windDataReplyReceived(...);
         // TODO void cloudDataReplyReceived(...);
+
+        //! @}
     };
 
 } // namespace