Document code

src/IO/Console.cpp

@@ -287,7 +287,7 @@ void Console::send(const QString &data)
         {
             append(dataToString(bin));
             m_timestampAdded = false;
-            if (m_cursor)
+            if (m_cursor && lineEnding() == LineEnding::NoLineEnding)
                 m_cursor->insertBlock();
         }
     }

src/IO/DataSources/Serial.cpp

@@ -356,9 +356,12 @@ void Serial::setBaudRate(const qint32 rate)
     LOG_INFO() << "Baud rate set to" << rate;
 }
 
+/**
+ * Changes the port index value, this value is later used by the @c openSerialPort()
+ * function.
+ */
 void Serial::setPortIndex(const quint8 portIndex)
 {
-    auto ports = validPorts();
     auto portId = portIndex - 1;
     if (portId >= 0 && portId < validPorts().count())
         m_portIndex = portIndex;

src/IO/Manager.cpp

@@ -6,8 +6,14 @@
 
 using namespace IO;
 
+/**
+ * Pointer to the only instance of the class.
+ */
 static Manager *INSTANCE = nullptr;
 
+/**
+ * Constructor function
+ */
 Manager::Manager()
     : m_writeEnabled(true)
     , m_maxBuzzerSize(1024 * 1024)
@@ -20,8 +26,14 @@ Manager::Manager()
     setWatchdogInterval(15);
 }
 
+/**
+ * Destructor function
+ */
 Manager::~Manager() { }
 
+/**
+ * Returns the only instance of the class
+ */
 Manager *Manager::getInstance()
 {
     if (!INSTANCE)
@@ -30,16 +42,25 @@ Manager *Manager::getInstance()
     return INSTANCE;
 }
 
+/**
+ * Returns @c true if a device is connected and its open in read-only mode
+ */
 bool Manager::readOnly()
 {
     return connected() && !m_writeEnabled;
 }
 
+/**
+ * Returns @c true if a device is connected and its open in read/write mode
+ */
 bool Manager::readWrite()
 {
     return connected() && m_writeEnabled;
 }
 
+/**
+ * Returns @c true if a device is currently selected and opened
+ */
 bool Manager::connected()
 {
     if (device())
@@ -48,41 +69,94 @@ bool Manager::connected()
     return false;
 }
 
+/**
+ * Returns @c true if a device is currently selected
+ */
 bool Manager::deviceAvailable()
 {
     return device() != nullptr;
 }
 
+/**
+ * Returns the interval of the watchdog in milliseconds. The watchdog is used to clear
+ * the data buffer if no data has been received in more than x milliseconds (default
+ * 15 ms, tested on a 300 baud rate MCU).
+ *
+ * This is useful for: a) Dealing when a device suddenly is disconnected
+ *                     b) Removing extra data between received frames
+ *
+ * Example:
+ *
+ *      RRRRRRRRR  watchdog clears buf.  RRRRRRRRR  watchdog clear buf.   RRRRRRRR
+ *     [--------] . - . - . - . - . - . [--------] . - . - . - . - . - . [--------]
+ *      Frame A   Interval of > 15 ms    Frame B   Interval of > 15 ms    Frame C
+ *
+ *  Note: in the representation above "R" means that the watchdog is reset, thus, the
+ *        data buffer is not cleared until we wait for another frame or communications
+ *        are interrupted.
+ *
+ * TODO: let the JSON project file define the watchdog timeout time.
+ */
 int Manager::watchdogInterval() const
 {
     return m_watchdog.interval();
 }
 
+/**
+ * Returns the maximum size of the buffer. This is useful to avoid consuming to much
+ * memory when a large block of invalid data is received (for example, when the user
+ * selects an invalid baud rate configuration).
+ */
 int Manager::maxBufferSize() const
 {
     return m_maxBuzzerSize;
 }
 
+/**
+ * Returns a pointer to the currently selected device.
+ *
+ * @warning you need to check this pointer before using it, it can have a @c nullptr
+ *          value during normal operations.
+ */
 QIODevice *Manager::device()
 {
     return m_device;
 }
 
+/**
+ * Returns the currently selected data source, possible return values:
+ * - @c DataSource::Serial  use a serial port as a data source
+ * - @c DataSource::Network use a network port as a data source
+ */
 Manager::DataSource Manager::dataSource() const
 {
     return m_dataSource;
 }
 
+/**
+ * Returns the start sequence string used by the application to know where to consider
+ * that a frame begins. If the start sequence is empty, then the application shall ignore
+ * incoming data. The only thing that wont ignore the incoming data will be the console.
+ */
 QString Manager::startSequence() const
 {
     return m_startSequence;
 }
 
+/**
+ * Returns the finish sequence string used by the application to know where to consider
+ * that a frame ends. If the start sequence is empty, then the application shall ignore
+ * incoming data. The only thing that wont ignore the incoming data will be the console.
+ */
 QString Manager::finishSequence() const
 {
     return m_finishSequence;
 }
 
+/**
+ * Returns the size of the data received (and successfully read) from the device in the
+ * format of a string.
+ */
 QString Manager::receivedDataLength() const
 {
     QString value;
@@ -111,6 +185,9 @@ QString Manager::receivedDataLength() const
     return QString("%1 %2").arg(value).arg(units);
 }
 
+/**
+ * Returns a list with the possible data source options.
+ */
 QStringList Manager::dataSourcesList() const
 {
     QStringList list;
@@ -119,6 +196,12 @@ QStringList Manager::dataSourcesList() const
     return list;
 }
 
+/**
+ * Tries to write the given @a data to the current device. Upon data write, the class
+ * emits the @a tx() signal for UI updating.
+ *
+ * @returns the number of bytes written to the target device
+ */
 qint64 Manager::writeData(const QByteArray &data)
 {
     // Write data to device
@@ -134,6 +217,10 @@ qint64 Manager::writeData(const QByteArray &data)
     return bytes;
 }
 
+/**
+ * Connects/disconnects the application from the currently selected device. This function
+ * is used as a convenience for the connect/disconnect button.
+ */
 void Manager::toggleConnection()
 {
     if (connected())
@@ -142,12 +229,16 @@ void Manager::toggleConnection()
         connectDevice();
 }
 
+/**
+ * Closes the currently selected device and tries to open & configure a new connection.
+ * A data source must be selected before calling this function.
+ */
 void Manager::connectDevice()
 {
     // Disconnect previous device (if any)
     disconnectDevice();
 
-    // Set device handler
+    // Try to open a serial port connection
     if (dataSource() == DataSource::Serial)
         setDevice(DataSources::Serial::getInstance()->openSerialPort());
 
@@ -178,6 +269,9 @@ void Manager::connectDevice()
     }
 }
 
+/**
+ * Disconnects from the current device and clears temp. data
+ */
 void Manager::disconnectDevice()
 {
     if (deviceAvailable())
@@ -200,12 +294,18 @@ void Manager::disconnectDevice()
     }
 }
 
+/**
+ * Enables/disables RW mode
+ */
 void Manager::setWriteEnabled(const bool enabled)
 {
     m_writeEnabled = enabled;
     emit writeEnabledChanged();
 }
 
+/**
+ * Changes the data source type. Check the @c dataSource() funciton for more information.
+ */
 void Manager::setDataSource(const DataSource source)
 {
     // Disconnect current device
@@ -217,24 +317,40 @@ void Manager::setDataSource(const DataSource source)
     emit dataSourceChanged();
 }
 
+/**
+ * Changes the maximum permited buffer size. Check the @c maxBufferSize() function for
+ * more information.
+ */
 void Manager::setMaxBufferSize(const int maxBufferSize)
 {
     m_maxBuzzerSize = maxBufferSize;
     emit maxBufferSizeChanged();
 }
 
+/**
+ * Changes the frame start sequence. Check the @c startSequence() function for more
+ * information.
+ */
 void Manager::setStartSequence(const QString &sequence)
 {
     m_startSequence = sequence;
     emit startSequenceChanged();
 }
 
+/**
+ * Changes the frame end sequence. Check the @c finishSequence() function for more
+ * information.
+ */
 void Manager::setFinishSequence(const QString &sequence)
 {
     m_finishSequence = sequence;
     emit finishSequenceChanged();
 }
 
+/**
+ * Changes the expiration interval of the watchdog timer. Check the @c watchdogInterval()
+ * function for more information.
+ */
 void Manager::setWatchdogInterval(const int interval)
 {
     m_watchdog.setInterval(interval);
@@ -242,6 +358,13 @@ void Manager::setWatchdogInterval(const int interval)
     emit watchdogIntervalChanged();
 }
 
+/**
+ * Read frames from temporary buffer, every frame that contains the appropiate start/end
+ * sequence is removed from the buffer as soon as its read.
+ *
+ * This function also checks that the buffer size does not exceed specified size
+ * limitations.
+ */
 void Manager::readFrames()
 {
     // No device connected, abort
@@ -279,12 +402,21 @@ void Manager::readFrames()
         clearTempBuffer();
 }
 
+/**
+ * Resets the watchdog timer before it expires. Check the @c watchdogInterval() function
+ * for more information.
+ */
 void Manager::feedWatchdog()
 {
     m_watchdog.stop();
     m_watchdog.start();
 }
 
+/**
+ * Reads incoming data from the serial device, updates the serial console object,
+ * registers incoming data to temporary buffer & extracts valid data frames from the
+ * buffer using the @c readFrame() function.
+ */
 void Manager::onDataReceived()
 {
     // Verify that device is still valid
@@ -313,16 +445,29 @@ void Manager::onDataReceived()
     emit rx();
 }
 
+/**
+ * Deletes the contents of the temporary buffer. This function is called automatically by
+ * the class when the temporary buffer size exceeds the limit imposed by the
+ * @c maxBufferSize() function.
+ */
 void Manager::clearTempBuffer()
 {
     m_dataBuffer.clear();
 }
 
+/**
+ * Called when the watchdog timer expires. For the moment, this function only clears the
+ * temporary data buffer.
+ */
 void Manager::onWatchdogTriggered()
 {
     clearTempBuffer();
 }
 
+/**
+ * Changes the target device pointer. Deletion should be handled by the interface
+ * implementation, not by this class.
+ */
 void Manager::setDevice(QIODevice *device)
 {
     disconnectDevice();

src/JSON/Frame.cpp

@@ -24,17 +24,28 @@
 
 using namespace JSON;
 
+/**
+ * Constructor function
+ */
 Frame::Frame(QObject *parent)
     : QObject(parent)
     , m_title("")
 {
 }
 
+/**
+ * Destructor function, free memory used by the @c Group objects before destroying an
+ * instance of this class.
+ */
 Frame::~Frame()
 {
     clear();
 }
 
+/**
+ * Resets the frame title and frees the memory used by the @c Group objects associated
+ * to the instance of the @c Frame object.
+ */
 void Frame::clear()
 {
     for (int i = 0; i < groupCount(); ++i)
@@ -44,21 +55,36 @@ void Frame::clear()
     m_groups.clear();
 }
 
+/**
+ * Returns the title of the frame.
+ */
 QString Frame::title() const
 {
     return m_title;
 }
 
+/**
+ * Returns the number of groups contained in the frame.
+ */
 int Frame::groupCount() const
 {
     return groups().count();
 }
 
+/**
+ * Returns a vector of pointers to the @c Group objects associated to this frame.
+ */
 QVector<Group *> Frame::groups() const
 {
     return m_groups;
 }
 
+/**
+ * Reads the frame information and all its asociated groups (and datatsets) from the given
+ * JSON @c object.
+ *
+ * @return @c true on success, @c false on failure
+ */
 bool Frame::read(const QJsonObject &object)
 {
     // Rest frame data