qdlt: Add some basic doc

Michael Foukarakis · Michael Foukarakis · commit 6f93dff755a7 · 2025-09-11T13:11:36.000+02:00
* Add some basic descriptions for the headers in qdlt/
  so that some relationships are clear in generated graphs.
* Some basic docs in locations where code is parsing DLT message(s)
  or DLT messages are created based on internal state.

This is not complete by far, most functions miss documentation
and there are no statements of intent anywhere.

Signed-off-by: Michael Foukarakis &lt;michael.foukarakis@bmw.de&gt;
diff --git a/qdlt/dlt_protocol.h b/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 */
diff --git a/qdlt/dltmessagematcher.h b/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:
diff --git a/qdlt/fieldnames.h b/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
diff --git a/qdlt/qdltargument.h b/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
 {
diff --git a/qdlt/qdltbase.h b/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:
diff --git a/qdlt/qdltconnection.h b/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;
diff --git a/qdlt/qdltcontrol.h b/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
diff --git a/qdlt/qdltctrlmsg.h b/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;
 };
diff --git a/qdlt/qdltdefaultfilter.h b/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:
diff --git a/qdlt/qdltexporter.h b/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
diff --git a/qdlt/qdltfile.h b/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:
diff --git a/qdlt/qdltfilter.h b/qdlt/qdltfilter.h
@@ -36,6 +36,9 @@
 #include "qdltmsg.h"
 
 
+/**
+ * Represents a filter set in the UI.
+ */
 class QDLT_EXPORT QDltFilter
 {
 public:
diff --git a/qdlt/qdltfilterindex.h b/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:
diff --git a/qdlt/qdltfilterlist.h b/qdlt/qdltfilterlist.h
@@ -35,7 +35,9 @@
 #include <QXmlStreamReader>
 #include <QXmlStreamWriter>
 
-
+/**
+ * A list of filters applied in the UI
+ */
 class QDLT_EXPORT QDltFilterList
 {
 public:
diff --git a/qdlt/qdltimporter.h b/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
diff --git a/qdlt/qdltipconnection.h b/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:
diff --git a/qdlt/qdltmessagedecoder.h b/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:
diff --git a/qdlt/qdltmsg.cpp b/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())
diff --git a/qdlt/qdltmsg.h b/qdlt/qdltmsg.h
diff --git a/qdlt/qdltoptmanager.h b/qdlt/qdltoptmanager.h
diff --git a/qdlt/qdltplugin.h b/qdlt/qdltplugin.h
diff --git a/qdlt/qdltsegmentedmsg.h b/qdlt/qdltsegmentedmsg.h
diff --git a/qdlt/qdltserialconnection.h b/qdlt/qdltserialconnection.h
diff --git a/qdlt/qdltsettingsmanager.h b/qdlt/qdltsettingsmanager.h
diff --git a/qdlt/qdlttcpconnection.h b/qdlt/qdlttcpconnection.h
diff --git a/qdlt/qdltudpconnection.h b/qdlt/qdltudpconnection.h
diff --git a/src/searchdialog.cpp b/src/searchdialog.cpp
