qdlt: Add some basic docs

qdlt/dlt_protocol.h

@@ -164,7 +164,10 @@
 #define DLT_SCOD_HEX        0x00010000
 #define DLT_SCOD_BIN        0x00018000
 /*
- * Definitions of DLT services.
+ * Definitions of DLT service IDs.
+ *
+ * Should correspond to AUTOSAR DLT protocol specification the DLT service
+ * implementation conforms to.
  */
 #define DLT_SERVICE_ID_SET_LOG_LEVEL                   0x01 /**< Service ID: Set log level */
 #define DLT_SERVICE_ID_SET_TRACE_STATUS                0x02 /**< Service ID: Set trace status */

qdlt/dltmessagematcher.h

@@ -11,6 +11,17 @@
 
 class QDltMsg;
 
+/**
+ * A class which can be used to set search parameters for matching on potential DLT messages.
+ *
+ * Offers functions to search different parts of a DLT message.
+ * Offers the option to search either the header, the payload, or both.
+ * Searches can be case-sensitive - default is case-insensitive.
+ * The pattern to search a payload can be either a regular expression or plain text.
+ *
+ * Currently used by the UI search dialog.
+ * @see SearchDialog
+ */
 class QDLT_EXPORT DltMessageMatcher
 {
 public:
@@ -46,9 +57,32 @@ class QDLT_EXPORT DltMessageMatcher
         m_messageIdFormat = msgIdFormat;
     }
 
+    /**
+     *
+     * @return `true` if `msg` matches all of:
+     *  - application ID set in `this`
+     *  - context ID set in `this`
+     *  - timestamp range set in `this`
+     *  - pattern matches either the `msg` header or payload
+     *  `false` otherwise.
+     *
+     *  @see SearchDialog::findMessages
+     */
     bool match(const QDltMsg& message, const Pattern& pattern) const;
+
 private:
+
+    /**
+     * Match the application ID in `appId` against `this`
+     *
+     * @return `true` if `this` has no application ID set or the IDs match exactly, false otherwise
+     */
     bool matchAppId(const QString& appId) const;
+    /**
+     * Match the context ID in `ctxId` against `this`
+     *
+     * @return `true` if `this` has no application ID set or the IDs match exactly, false otherwise
+     */
     bool matchCtxId(const QString& ctxId) const;
     bool matchTimestampRange(unsigned int ts) const;
 private:

qdlt/fieldnames.h

@@ -6,6 +6,12 @@
 #include <QObject>
 #include <QString>
 
+/**
+ * Class to obtain human-readable names for DLT message parts,
+ * and UI element properties.
+ *
+ * @see MainWindow::initView
+ */
 class QDLT_EXPORT FieldNames : public QObject
 {
     Q_OBJECT
@@ -42,9 +48,9 @@ class QDLT_EXPORT FieldNames : public QObject
     static bool getColumnShown(Fields cn,QDltSettingsManager *settings = NULL);
 
 signals:
-    
+
 public slots:
-    
+
 };
 
 #endif // FIELDNAMES_H

qdlt/qdltargument.h

@@ -31,7 +31,8 @@
 //! One argument of a DLT message.
 /*!
   This class contains one argument of a DLT message.
-  A QDltMessage contains several Arguments.
+  A QDltMessage contains several QDltArgument, like a DLT message contains
+  multiple arguments.
 */
 class QDLT_EXPORT QDltArgument
 {

qdlt/qdltbase.h

@@ -28,10 +28,11 @@
 
 constexpr const auto DLT_MAX_MESSAGE_LEN = 1024*64;
 
-//! Base class for all DLT classes.
-/*!
-  This class contains helper functions needed for all DLT operations and classes.
-*/
+/**
+ * Base class for all DLT classes.
+ *
+ * This class contains helper functions needed for all DLT operations and classes.
+ */
 class QDLT_EXPORT QDlt
 {
 public:

qdlt/qdltconnection.h

@@ -82,6 +82,11 @@ class QDLT_EXPORT QDltDataView
     int m_position;
 };
 
+/**
+ * Base class for classes representing a connection for user commands & UI.
+ *
+ * Has concrete methods.
+ */
 class QDLT_EXPORT QDltConnection
 {
 
@@ -102,6 +107,11 @@ class QDLT_EXPORT QDltConnection
     bool parseAscii(QDltMsg &msg);
 
     void clear();
+    /**
+     * Add data to a connection, to be parsed.
+     *
+     * @see MainWindow::read
+     */
     void add(const QByteArray &bytes);
 
     QByteArray data;

qdlt/qdltcontrol.h

@@ -32,6 +32,17 @@
 
 #include "export_rules.h"
 
+/**
+ * This class contains various signals used in MainWindow, corresponding to user commands.
+ * Execution of the commands is in UI code. Signals defined here are
+ * connected to slots in e.g. MainWindow.
+ * (rem. private slots can be invoked by arbitrary components)
+ *
+ * Also passed to plugins via MainWindow -> QDltPluginManager
+ *
+ * @see MainWindow::sendInjection
+ * @see MainWindow::jumpToMsgSignal
+ */
 class QDLT_EXPORT QDltControl : public QObject
 {
       Q_OBJECT

qdlt/qdltctrlmsg.h

@@ -12,6 +12,16 @@
 
 namespace qdlt::msg::payload {
 
+/**
+ * Most DLT service IDs referenced here can be found in the AUTOSAR DLT specification.
+ *
+ * Note the AUTOSAR spec does not reserve IDs.
+ */
+
+/**
+ * A struct associated with the `GetLogInfo` DLT service command,
+ * to retrieve log levels for all registered contexts.
+ */
 struct GetLogInfo {
     struct App {
         struct Ctx {
@@ -30,15 +40,27 @@ struct GetLogInfo {
     std::vector<App> apps;
 };
 
+/**
+ * A struct associated with the `GetSoftwareVersion` DLT service command,
+ * to retrieve a string denoting the system's software version.
+ */
 struct GetSoftwareVersion {
 };
 
+/**
+ * A struct associated with the `GetDefaultLogLevel` DLT service command,
+ * to retrieve the currently set default log level.
+ */
 struct GetDefaultLogLevel
 {
     uint8_t logLevel;
     uint8_t status;
 };
 
+/**
+ * A struct associated with the `GetDefaultLogLevel` DLT service command,
+ * to set a log level.
+ */
 struct SetLogLevel {
     uint8_t status;
 };

qdlt/qdltdefaultfilter.h

@@ -36,6 +36,12 @@
 #include "qdltfilterlist.h"
 
 
+/**
+ * "Default" filters loaded by MainWindow - initialises the indexer.
+ * this ∋ `QDltFilterList` ∋ `QDltFilter`
+ *
+ * @see MainWindow
+ */
 class QDLT_EXPORT QDltDefaultFilter
 {
 public:

qdlt/qdltexporter.h

@@ -15,6 +15,13 @@
 #define QDLT_DEFAULT_EXPORT_SIGNATURE "ITSOEACNYUMRP"
 #define QDLT_DEFAULT_EXPORT_DELIMITER ','
 
+/**
+ * Class used for UI export functions. Currently implemented as a thread that must be fed
+ * messages to export.
+ *
+ * There is no interface toward a collection of DLT messages, but instead
+ * functions are referencing single QDltMsg instances. This is suboptimal.
+ */
 class QDLT_EXPORT QDltExporter : public QThread
 {
     Q_OBJECT

qdlt/qdltfile.h

@@ -35,6 +35,9 @@
 #include <time.h>
 #include <QCache>
 
+/**
+ * Object containing a single QFile and an index to offsets of DLT messages in it.
+ */
 class QDLT_EXPORT QDltFileItem
 {
 public:
@@ -49,11 +52,12 @@ class QDLT_EXPORT QDltFileItem
 
 };
 
-//! Access to a DLT log file.
-/*!
-  This class provide access to DLT log file.
-  This class is currently not thread safe.
-*/
+/**
+ * Access to a DLT log file.
+ *
+ * This class provide access to DLT log file.
+ * This class is currently not thread safe.
+ */
 class QDLT_EXPORT QDltFile : public QDlt
 {
 public:

qdlt/qdltfilter.h

@@ -36,6 +36,9 @@
 #include "qdltmsg.h"
 
 
+/**
+ * Represents a filter set in the UI.
+ */
 class QDLT_EXPORT QDltFilter
 {
 public:

qdlt/qdltfilterindex.h

@@ -32,6 +32,11 @@
 #include "export_rules.h"
 #include "qdltfilterlist.h"
 
+/**
+ * Maybe supposed to represent a file with filters applied to it. Unclear usage of index.
+ *
+ * Missing getters / interface.
+ */
 class QDLT_EXPORT QDltFilterIndex
 {
 public:

qdlt/qdltfilterlist.h

@@ -35,7 +35,9 @@
 #include <QXmlStreamReader>
 #include <QXmlStreamWriter>
 
-
+/**
+ * A list of filters applied in the UI
+ */
 class QDLT_EXPORT QDltFilterList
 {
 public:

qdlt/qdltimporter.h

@@ -156,6 +156,12 @@ typedef struct mdf_hdr {
         quint64 link_count;     /* number of links in link section */
 } PACKED mdf_hdr_t;
 
+/**
+ * Class used for UI import functions. Currently implemented as a thread that must be fed
+ * messages individually - this is suboptimal.
+ *
+ * Function names are nondescript.
+ */
 class QDLT_EXPORT QDltImporter : public QThread
 {
     Q_OBJECT

qdlt/qdltipconnection.h

@@ -32,6 +32,15 @@
 #include "export_rules.h"
 #include "qdltconnection.h"
 
+/**
+ * A (conceptual) connection toward a DLT service.
+ *
+ * Currently set up as an inheritance scheme - QDltConnection has concrete functions
+ * for parsing.
+ * This class keeps track of the remote host(name). Also port, although IP has no port info.
+ *
+ * Used by the UI (main window).
+ */
 class QDLT_EXPORT QDltIPConnection : public QDltConnection
 {
 public:

qdlt/qdltmessagedecoder.h

@@ -27,6 +27,12 @@
 
 class QDltMsg;
 
+/**
+ * An interface for modifying a QDltMsg based on plugin-specific functionality.
+ *
+ * Designing the decoding to be done by expecting a message to be its own object
+ * is suboptimal and does not allow efficient organisation (memory, temporal, or otherwise).
+ */
 class QDLT_EXPORT QDltMessageDecoder
 {
 public:

qdlt/qdltmsg.cpp

@@ -309,6 +309,15 @@ quint32 QDltMsg::checkMsgSize(const char *data,quint32 size,bool supportDLTv2)
     }
 }
 
+/**
+ * Attempt to parse a valid DLT message from `buf`, with an optional storage header.
+ *
+ * It will attempt to parse DLTv1 only if `supportDLTv2` is `false`.
+ *
+ * @return `false` if there is not enough data in `buf` for a valid message header or
+ * the entire message as indicated in the header's length field. Also `false` if
+ * arguments could not be parsed correctly. Otherwise, `true`.
+ */
 bool QDltMsg::setMsg(const QByteArray& buf, bool withStorageHeader,bool supportDLTv2)
 {
     unsigned int offset;
@@ -926,6 +935,14 @@ bool QDltMsg::parseArguments()
     return true;
 }
 
+/**
+ * Attempt to create a valid DLT messages in `buf`, optionally
+ * preceded by a storage header, from the state of `this` object.
+ *
+ * Modifies `this.payload` to contain the message's arguments.
+ *
+ * @return `false` if calling `QDltArgument::getArgument` fails, `true` otherwise
+ */
 bool QDltMsg::getMsg(QByteArray &buf,bool withStorageHeader) {
     DltStorageHeader storageheader;
     DltStandardHeader standardheader;
@@ -1073,6 +1090,12 @@ int QDltMsg::sizeArguments() const
     return arguments.size();
 }
 
+/**
+ * Set `argument` to the argument of this message at `index`.
+ *
+ * @return `false` if `index` is outside the range of currently contained arguments, `true`
+ * otherwise.
+ */
 bool QDltMsg::getArgument(int index,QDltArgument &argument) const
 {
       if(index<0 || index>=arguments.size())