Initial cleanup of (Doxygen) documentation.

doc/README

@@ -3,35 +3,12 @@ Linux/Mac OS X
 To install doxygen: 
 $sudo apt-get install doxygen
 
-If the above does not work go to:
-http://www.stack.nl/~dimitri/doxygen/download.html for the correct download.
-
-Then go to the following website for inforamtion on the install:
-http://www.stack.nl/~dimitri/doxygen/install.html
+doxyqml:
+https://github.com/agateau/doxyqml
+$sudo pip3 install doxyqml
 
 Then to generate the html, run the following code while you are in the qgroundcontrol/doc directory:
 $doxygen Doxyfile
 
 The html file index.html should be in doc/html unless you chenged the output directory. 
 
-The other option for generating the documentation is to use the wizard:
-$doxywizard &
-
-doxywizard information:
-http://www.stack.nl/~dimitri/doxygen/doxywizard_usage.html
-
-Or go to the Doxygen Manual for information at the website noted below.
-
-Windows
-=======
-Go to the following website for the correct download and follow the wizard to install:
-http://www.stack.nl/~dimitri/doxygen/download.html
-
-Run the wizard to generate the documentation. 
-Go to the website below or the Doxygen Manual for information on running doxywizard.
-http://www.stack.nl/~dimitri/doxygen/doxywizard_usage.html
-
-Doxygen Manual
-==============
-http://www.stack.nl/~dimitri/doxygen/
-

doc/links.md

+# Link Management
+
+The LinkManager creates, configures and maintains communication links. Links are created either through the user
+interface or programmatically. The LinkConfiguration base classs defines the means to configure a given link
+while the LinkInterface exposes the link itself.
+
+Link specializations such as UDPLink, TCPLink, SerialLink, etc. are implemented in their own derived classes as well
+as their equivalent configuration derivations such as UDPConfiguration, TCPConfiguration, SerialConfiguration, etc.
+
+Links are primarily responsible to send and receive (MAVLink) data to and from a vehicle. When data arrives, the link will emit a
+LinkInterface::bytesReceived signal and when data needs to be sent back to a vehicle, the code uses its
+LinkInterface::writeBytesSafe method.
+
+<div align="center">
+<img src="../links.svg">
+</div>
\ No newline at end of file

doc/qgroundcontrol.md

+QGroundControl Architecture Documentation {#mainpage}
+=========================================
+
+* [Link Management](links.md)
+* [Vehicle Management](vehicleMgmt.md)

doc/vehicleMgmt.md

+# Vehicle Management
+
+The singleton MAVLinkProtocol implements the target slot for all LinkInterface::bytesReceived signals. As data is received, it parses and builds MAVLink messages.
+All messages are then sent through a MAVLinkProcotol::messageReceived signal. In addition, when it detects a heartbeat message,
+it emits MAVLinkProcotol::vehicleHeartbeatInfo signals. 
+
+The singleton MultiVehicleManager is responsible for creating and maintaining instances of the Vehicle class. When it receives a MAVLinkProcotol::vehicleHeartbeatInfo
+signal for the first time, it creates a vehicle instance, recording the vehicle ID and the link used. 
+
+The Vehicle class holds all the functionality to handle vehicles. It receives all messages sent from the vehicle and manage all messages and commands to that vehicle.
+
+<div align="center">
+<img src="../vehicleMgmt.svg">
+</div>
\ No newline at end of file

src/Audio/AudioOutput.h

@@ -19,6 +19,7 @@
 
 class QGCApplication;
 
+/// Text to Speech Interface
 class AudioOutput : public QGCTool
 {
     Q_OBJECT
@@ -29,6 +30,7 @@ public:
     static QString  fixTextMessageForAudio  (const QString& string);
 
 public slots:
+    /// Convert string to speech output and say it
     void            say                     (const QString& text);
 
 private slots:

src/CmdLineOptParser.cc

@@ -9,9 +9,8 @@
 
 
 /// @file
-///     @brief Command line option parser
-///
-///     @author Don Gagne <don@thegagnes.com>
+/// @brief Command line option parser implementation
+/// @author Don Gagne <don@thegagnes.com>
 
 #include "CmdLineOptParser.h"
 

src/CmdLineOptParser.h

@@ -9,20 +9,18 @@
 
 
 /// @file
-///     @brief Command line option parser
-///
-///     @author Don Gagne <don@thegagnes.com>
+/// @brief  Command line option parser declaration
+/// @author Don Gagne <don@thegagnes.com>
 
-#ifndef CMDLINEOPTPARSER_H
-#define CMDLINEOPTPARSER_H
+#pragma once
 
 #include <QString>
 #include <cstring>
 
 /// @brief Structure used to pass command line options to the ParseCmdLineOptions function.
 typedef struct {
-    const char* optionStr;      ///< command line option, for example "--foo"
-    bool*       optionFound;    ///< if option is found this variable will be set to true
+    const char* optionStr;      ///< Command line option, for example "--foo"
+    bool*       optionFound;    ///< If option is found this variable will be set to true
     QString*    optionArg;      ///< Option has additional argument, form is option:arg
 } CmdLineOpt_t;
 
@@ -32,4 +30,3 @@ void ParseCmdLineOptions(int&           argc,
                          size_t         cOpts,
                          bool           removeParsedOptions);
 
-#endif

src/FirmwarePlugin/FirmwarePlugin.h

@@ -126,7 +126,7 @@ public:
     virtual QString gotoFlightMode(void) const;
 
     /// Returns the flight mode which the vehicle will be for follow me
-    virtual QString followFlightMode(void) const { return QString(); };
+    virtual QString followFlightMode(void) const { return QString(); }
 
     /// Set guided flight mode
     virtual void setGuidedMode(Vehicle* vehicle, bool guidedMode);
@@ -145,7 +145,7 @@ public:
     virtual void guidedModeTakeoff(Vehicle* vehicle, double takeoffAltRel);
 
     /// @return The minimum takeoff altitude (relative) for guided takeoff.
-    virtual double minimumTakeoffAltitude(Vehicle* vehicle) { Q_UNUSED(vehicle); return 10; }
+    virtual double minimumTakeoffAltitude(Vehicle* /*vehicle*/) { return 10; }
 
     /// Command the vehicle to start the mission
     virtual void startMission(Vehicle* vehicle);
@@ -217,21 +217,21 @@ public:
     virtual void getParameterMetaDataVersionInfo(const QString& metaDataFile, int& majorVersion, int& minorVersion);
 
     /// Returns the internal resource parameter meta date file.
-    virtual QString internalParameterMetaDataFile(Vehicle* vehicle) { Q_UNUSED(vehicle); return QString(); }
+    virtual QString internalParameterMetaDataFile(Vehicle* /*vehicle*/) { return QString(); }
 
     /// Loads the specified parameter meta data file.
     /// @return Opaque parameter meta data information which must be stored with Vehicle. Vehicle is responsible to
     ///         call deleteParameterMetaData when no longer needed.
-    virtual QObject* loadParameterMetaData(const QString& metaDataFile) { Q_UNUSED(metaDataFile); return nullptr; }
+    virtual QObject* loadParameterMetaData(const QString& /*metaDataFile*/) { return nullptr; }
 
     /// Returns the FactMetaData associated with the parameter name
     ///     @param opaqueParameterMetaData Opaque pointer returned from loadParameterMetaData
     ///     @param name Parameter name
-    virtual FactMetaData* getMetaDataForFact(QObject* parameterMetaData, const QString& name, MAV_TYPE vehicleType) { Q_UNUSED(parameterMetaData); Q_UNUSED(name); Q_UNUSED(vehicleType); return nullptr; }
+    virtual FactMetaData* getMetaDataForFact(QObject* /*parameterMetaData*/, const QString& /*name*/, MAV_TYPE /*vehicleType*/) { return nullptr; }
 
     /// Adds the parameter meta data to the Fact
     ///     @param opaqueParameterMetaData Opaque pointer returned from loadParameterMetaData
-    virtual void addMetaDataToFact(QObject* parameterMetaData, Fact* fact, MAV_TYPE vehicleType) { Q_UNUSED(parameterMetaData); Q_UNUSED(fact); Q_UNUSED(vehicleType); return; }
+    virtual void addMetaDataToFact(QObject* /*parameterMetaData*/, Fact* /*fact*/, MAV_TYPE /*vehicleType*/) { return; }
 
     /// List of supported mission commands. Empty list for all commands supported.
     virtual QList<MAV_CMD> supportedMissionCommands(void);
@@ -247,19 +247,19 @@ public:
     virtual int remapParamNameHigestMinorVersionNumber(int majorVersionNumber) const;
 
     /// @return true: Motors are coaxial like an X8 config, false: Quadcopter for example
-    virtual bool multiRotorCoaxialMotors(Vehicle* vehicle) { Q_UNUSED(vehicle); return false; }
+    virtual bool multiRotorCoaxialMotors(Vehicle* /*vehicle*/) { return false; }
 
     /// @return true: X confiuration, false: Plus configuration
-    virtual bool multiRotorXConfig(Vehicle* vehicle) { Q_UNUSED(vehicle); return false; }
+    virtual bool multiRotorXConfig(Vehicle* /*vehicle*/) { return false; }
 
     /// Return the resource file which contains the set of params loaded for offline editing.
-    virtual QString offlineEditingParamFile(Vehicle* vehicle) { Q_UNUSED(vehicle); return QString(); }
+    virtual QString offlineEditingParamFile(Vehicle* /*vehicle*/) { return QString(); }
 
     /// Return the resource file which contains the brand image for the vehicle for Indoor theme.
-    virtual QString brandImageIndoor(const Vehicle* vehicle) const { Q_UNUSED(vehicle) return QString(); }
+    virtual QString brandImageIndoor(const Vehicle* /*vehicle*/) const { return QString(); }
 
     /// Return the resource file which contains the brand image for the vehicle for Outdoor theme.
-    virtual QString brandImageOutdoor(const Vehicle* vehicle) const { Q_UNUSED(vehicle) return QString(); }
+    virtual QString brandImageOutdoor(const Vehicle* /*vehicle*/) const { return QString(); }
 
     /// Return the resource file which contains the vehicle icon used in the flight view when the view is dark (Satellite for instance)
     virtual QString vehicleImageOpaque(const Vehicle* vehicle) const;
@@ -324,7 +324,7 @@ public:
     /// Allows the Firmware plugin to override the facts meta data.
     ///     @param vehicleType - Type of current vehicle
     ///     @param metaData - MetaData for fact
-    virtual void adjustMetaData(MAV_TYPE vehicleType, FactMetaData* metaData) {Q_UNUSED(vehicleType); Q_UNUSED(metaData);}
+    virtual void adjustMetaData(MAV_TYPE /*vehicleType*/, FactMetaData* /*metaData*/) {}
 
     /// Sends the appropriate mavlink message for follow me support
     virtual void sendGCSMotionReport(Vehicle* vehicle, FollowMe::GCSMotionReport& motionReport, uint8_t estimatationCapabilities);
@@ -345,7 +345,7 @@ protected:
     bool _setFlightModeAndValidate(Vehicle* vehicle, const QString& flightMode);
 
     // returns url with latest firmware release information.
-    virtual QString _getLatestVersionFileUrl(Vehicle* vehicle) { Q_UNUSED(vehicle); return QString(); }
+    virtual QString _getLatestVersionFileUrl(Vehicle* /*vehicle*/) { return QString(); }
 
     // Callback to process file with latest release information
     virtual void _versionFileDownloadFinished(QString& remoteFile, QString& localFile, Vehicle* vehicle);

src/JsonHelper.h

@@ -14,8 +14,13 @@
 #include <QVariantList>
 #include <QGeoCoordinate>
 
+/// @file
+/// @author Don Gagne <don@thegagnes.com>
+
 class QmlObjectListModel;
 
+/// @brief Json manipulation helper class.
+/// Primarily used for parsing and processing Fact metadata.
 class JsonHelper
 {
 public:

src/LogCompressor.cc

@@ -10,9 +10,9 @@
 
 /**
  * @file
- *   @brief Implementation of class LogCompressor. This class reads in a file containing messages and translates it into a tab-delimited CSV file.
+ *   @brief Implementation of class LogCompressor.
+ *          This class reads in a file containing messages and translates it into a tab-delimited CSV file.
  *   @author Lorenz Meier <mavteam@student.ethz.ch>
- *
  */
 
 #include "LogCompressor.h"

src/LogCompressor.h

-#ifndef LOGCOMPRESSOR_H
-#define LOGCOMPRESSOR_H
+/****************************************************************************
+ *
+ * (c) 2009-2020 QGROUNDCONTROL PROJECT <http://www.qgroundcontrol.org>
+ *
+ * QGroundControl is licensed according to the terms in the file
+ * COPYING.md in the root of the source code directory.
+ *
+ ****************************************************************************/
+
+#pragma once
 
 #include <QThread>
 
+/**
+ * @file
+ *   @brief Declaration of class LogCompressor.
+ *          This class reads in a file containing messages and translates it into a tab-delimited CSV file.
+ *   @author Lorenz Meier <mavteam@student.ethz.ch>
+ */
+
 class LogCompressor : public QThread
 {
     Q_OBJECT
@@ -37,5 +52,3 @@ private:
     void _signalCriticalError(const QString& msg);
     
 };
-
-#endif // LOGCOMPRESSOR_H
\ No newline at end of file

src/QGCComboBox.cc

@@ -7,13 +7,6 @@
  *
  ****************************************************************************/
 
-
-/// @file
-///     @brief Subclass of QComboBox. Mainly used for unit test so you can simulate a user selection
-///             with correct signalling.
-///
-///     @author Don Gagne <don@thegagnes.com>
-
 #include "QGCComboBox.h"
 
 QGCComboBox::QGCComboBox(QWidget* parent) :

src/QGCComboBox.h

@@ -7,9 +7,7 @@
  *
  ****************************************************************************/
 
-
-#ifndef QGCComboBox_H
-#define QGCComboBox_H
+#pragma once
 
 #include <QComboBox>
 
@@ -28,6 +26,3 @@ public:
 	/// @brief Sets the current index on the combo. Signals activated, as well as currentIndexChanged.
 	void simulateUserSetCurrentIndex(int index);
 };
-
-
-#endif

src/TerrainTile.cc

+/****************************************************************************
+ *
+ * (c) 2009-2020 QGROUNDCONTROL PROJECT <http://www.qgroundcontrol.org>
+ *
+ * QGroundControl is licensed according to the terms in the file
+ * COPYING.md in the root of the source code directory.
+ *
+ ****************************************************************************/
+
 #include "TerrainTile.h"
 #include "JsonHelper.h"
 #include "QGCMapEngine.h"
@@ -7,7 +16,7 @@
 #include <QJsonArray>
 #include <QDataStream>
 
-QGC_LOGGING_CATEGORY(TerrainTileLog, "TerrainTileLog")
+QGC_LOGGING_CATEGORY(TerrainTileLog, "TerrainTileLog");
 
 const char*  TerrainTile::_jsonStatusKey        = "status";
 const char*  TerrainTile::_jsonDataKey          = "data";
@@ -43,7 +52,6 @@ TerrainTile::~TerrainTile()
     }
 }
 
-
 TerrainTile::TerrainTile(QByteArray byteArray)
     : _minElevation(-1.0)
     , _maxElevation(-1.0)

src/Vehicle/MultiVehicleManager.h

@@ -40,14 +40,15 @@ public:
 
     Q_PROPERTY(bool                 activeVehicleAvailable          READ activeVehicleAvailable                                         NOTIFY activeVehicleAvailableChanged)
     Q_PROPERTY(bool                 parameterReadyVehicleAvailable  READ parameterReadyVehicleAvailable                                 NOTIFY parameterReadyVehicleAvailableChanged)
+    /// The current, active vehicle
     Q_PROPERTY(Vehicle*             activeVehicle                   READ activeVehicle                  WRITE setActiveVehicle          NOTIFY activeVehicleChanged)
+    /// The list of all connected vehicles
     Q_PROPERTY(QmlObjectListModel*  vehicles                        READ vehicles                                                       CONSTANT)
+    /// Enable sending heartbeats to the vehicle (defaults to true)
     Q_PROPERTY(bool                 gcsHeartBeatEnabled             READ gcsHeartbeatEnabled            WRITE setGcsHeartbeatEnabled    NOTIFY gcsHeartBeatEnabledChanged)
-
     /// A disconnected vehicle used for offline editing. It will match the vehicle type specified in Settings.
     Q_PROPERTY(Vehicle*             offlineEditingVehicle           READ offlineEditingVehicle                                          CONSTANT)
-
-    //-- The current vehicle's last known location
+    /// The current vehicle's last known location
     Q_PROPERTY(QGeoCoordinate       lastKnownLocation               READ lastKnownLocation                                              NOTIFY lastKnownLocationChanged)
 
     // Methods
@@ -91,7 +92,9 @@ signals:
     void activeVehicleChanged           (Vehicle* activeVehicle);
     void gcsHeartBeatEnabledChanged     (bool gcsHeartBeatEnabled);
     void lastKnownLocationChanged       ();
+#ifndef DOXYGEN_SKIP
     void _deleteVehiclePhase2Signal     (void);
+#endif
 
 private slots:
     void _deleteVehiclePhase1           (Vehicle* vehicle);

src/VehicleSetup/Bootloader.h

@@ -20,7 +20,7 @@
 
 #include <stdint.h>
 
-/// Bootloader Utility routines. Works with PX4 bootloader and 3DR Radio bootloader.
+/// Bootloader Utility routines. Works with PX4 and 3DR Radio bootloaders.
 class Bootloader : public QObject
 {
     Q_OBJECT

src/comm/LinkConfiguration.h

@@ -14,7 +14,6 @@
 class LinkInterface;
 
 /// Interface holding link specific settings.
-
 class LinkConfiguration : public QObject
 {
     Q_OBJECT

src/comm/LinkInterface.h

@@ -25,9 +25,8 @@
 class LinkManager;
 
 /**
-* The link interface defines the interface for all links used to communicate
-* with the groundstation application.
-*
+* @brief The link interface defines the interface for all links used to communicate
+* with the ground station application.
 **/
 class LinkInterface : public QThread
 {

src/comm/LinkManager.h

@@ -44,7 +44,7 @@ class UDPConfiguration;
 class AutoConnectSettings;
 class LogReplayLink;
 
-/// Manage communication links
+/// @brief Manage communication links
 ///
 /// The Link Manager organizes the physical Links. It can manage arbitrary
 /// links and takes care of connecting them as well assigning the correct
@@ -54,7 +54,7 @@ class LinkManager : public QGCTool
 {
     Q_OBJECT
 
-    /// Unit Test has access to private constructor/destructor
+    // Unit Test has access to private constructor/destructor
     friend class LinkManagerTest;
 
 public:
@@ -68,7 +68,7 @@ public:
     Q_PROPERTY(QStringList          serialPortStrings   READ serialPortStrings                                                  NOTIFY commPortStringsChanged)
     Q_PROPERTY(QStringList          serialPorts         READ serialPorts                                                        NOTIFY commPortsChanged)
 
-    // Create/Edit Link Configuration
+    /// Create/Edit Link Configuration
     Q_INVOKABLE LinkConfiguration*  createConfiguration         (int type, const QString& name);
     Q_INVOKABLE LinkConfiguration*  startConfigurationEditing   (LinkConfiguration* config);
     Q_INVOKABLE void                cancelConfigurationEditing  (LinkConfiguration* config) { delete config; }

src/comm/LogReplayLink.h

@@ -47,6 +47,7 @@ private:
     QString             _logFilename;
 };
 
+/// Pseudo link that reads a telemetry log and feeds it into the application.
 class LogReplayLink : public LinkInterface
 {
     Q_OBJECT

src/comm/MAVLinkProtocol.h

@@ -35,7 +35,7 @@ Q_DECLARE_LOGGING_CATEGORY(MAVLinkProtocolLog)
  *
  * MAVLink is a generic communication protocol for micro air vehicles.
  * for more information, please see the official website.
- * @ref http://pixhawk.ethz.ch/software/mavlink/
+ * @ref https://mavlink.io
  **/
 class MAVLinkProtocol : public QGCTool
 {

src/comm/SerialLink.h

@@ -43,6 +43,7 @@ Q_DECLARE_METATYPE(QSerialPort::SerialPortError)
 
 Q_DECLARE_LOGGING_CATEGORY(SerialLinkLog)
 
+/// SerialLink configuration
 class SerialConfiguration : public LinkConfiguration
 {
     Q_OBJECT