qdlt: Add some basic docs

Michael Foukarakis · Michael Foukarakis · commit 74b922c8c1d9 · 2025-08-28T14:04:57.000+02:00
Add some basic descriptions for the headers in qdlt/
so that some relationships are clear in generated graphs.

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/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:
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
@@ -32,6 +32,9 @@
 #include "export_rules.h"
 #include "qdltmsg.h"
 
+/**
+ * Unused.
+ */
 class QDLT_EXPORT QDltDataView
 {
 public:
diff --git a/qdlt/qdltcontrol.h b/qdlt/qdltcontrol.h
@@ -32,6 +32,10 @@
 
 #include "export_rules.h"
 
+/**
+ * This class contains various functions relevant to the UI,
+ * corresponding to user commands.
+ */
 class QDLT_EXPORT QDltControl : public QObject
 {
       Q_OBJECT
diff --git a/qdlt/qdltctrlmsg.h b/qdlt/qdltctrlmsg.h
@@ -12,6 +12,10 @@
 
 namespace qdlt::msg::payload {
 
+/**
+ * A struct associated with the `GetLogInfo` DLT command,
+ * to retrieve log levels for all registered contexts.
+ */
 struct GetLogInfo {
     struct App {
         struct Ctx {
@@ -30,31 +34,52 @@ struct GetLogInfo {
     std::vector<App> apps;
 };
 
+/**
+ * A struct associated with the `GetSoftwareVersion` DLT command,
+ * to retrieve a string denoting the system's software version.
+ */
 struct GetSoftwareVersion {
 };
 
+/**
+ * A struct associated with the `GetDefaultLogLevel` DLT command,
+ * to retrieve the currently set default log level.
+ */
 struct GetDefaultLogLevel
 {
     uint8_t logLevel;
     uint8_t status;
 };
 
+/**
+ * A struct associated with the `GetDefaultLogLevel` DLT command,
+ * to set a log level.
+ */
 struct SetLogLevel {
     uint8_t status;
 };
 
+/**
+ * ???
+ */
 struct Timezone {
     uint8_t status;
     int32_t timezone;
     uint8_t isDst;
 };
 
+/**
+ * ???
+ */
 struct UnregisterContext {
     uint8_t status;
     QString appid;
     QString ctxid;
 };
 
+/**
+ * ???
+ */
 struct Uninteresting {
     uint32_t serviceId;
 };
diff --git a/qdlt/qdltdefaultfilter.h b/qdlt/qdltdefaultfilter.h
@@ -36,6 +36,11 @@
 #include "qdltfilterlist.h"
 
 
+/**
+ * XXX
+ * Unclear usage. Maybe intended to represent filters set in the UI but only used in indexer.
+ * Unclear difference to `QDltFilter`.
+ */
 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,10 @@
 #include "qdltmsg.h"
 
 
+/**
+ * Represents filters set in the UI.
+ * Unclear difference to `QDltDefaultFilter`.
+ */
 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,11 @@
 #include "export_rules.h"
 #include "qdltconnection.h"
 
+/**
+ * A (conceptual) connection toward a DLT service.
+ *
+ * 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.h b/qdlt/qdltmsg.h
@@ -28,18 +28,18 @@
 #include "qdltbase.h"
 #include "qdltargument.h"
 
-//! Access to a DLT message.
-/*!
-  This class provide access to a single DLT message from a DLT log file.
-  This class is currently not thread safe.
-*/
+/**
+ * An object modelling a DLT message.
+ * Can be used to create custom messages and to parse valid DLT messages (e.g. from a file).
+ *
+ * @warning No functions in this class are thread-safe.
+ */
 class QDLT_EXPORT QDltMsg
 {
 public:
-    //! Constructor.
-    /*!
-      This call clears all variables of the argument.
-    */
+    /**
+     * Constructor. Clears all variables of the argument.
+     */
     QDltMsg();
 
     //! The type of the DLT message.
diff --git a/qdlt/qdltoptmanager.h b/qdlt/qdltoptmanager.h
@@ -41,6 +41,13 @@ enum class e_inputmode
     SERIAL = 2,
 };
 
+/**
+ * Holder for application options (UI).
+ *
+ * Unclear difference with QDltSettingsManager
+ *
+ * Some nondescript, nontrivial items need further doc.
+ */
 class QDLT_EXPORT QDltOptManager
 {
 public:
diff --git a/qdlt/qdltplugin.h b/qdlt/qdltplugin.h
@@ -8,10 +8,10 @@
 #include "export_rules.h"
 
 
-//! Access class to a DLT Plugin to decode, view and control DLT messages
-/*!
-  This class loads a DLT Viewer Plugin library and provides functions to access the plugin.
-*/
+/**
+ * Class representing a DLT plugin. Plugins can be used to decode, view and control DLT messages.
+ * This class loads a DLT Viewer Plugin library and provides functions to access the plugin.
+ */
 class QDLT_EXPORT QDltPlugin
 {
 public:
diff --git a/qdlt/qdltsegmentedmsg.h b/qdlt/qdltsegmentedmsg.h
@@ -26,10 +26,16 @@
 
 #include <qdltmsg.h>
 
-//! Combine segmented network messages
-/*!
-  This class combines several segmented network message to a single message
-*/
+/**
+ * Combine segmented network messages
+ * This class combines several segmented network message to a single message
+ *
+ * this -> DltSegmentationPlugin::decodeMsg -> QDltMsg
+ * ^
+ * This usage is suboptimal - this class has a straightforward conversion to QDltMsg that should be
+ * part of this class' functions.
+ *
+ */
 class QDLT_EXPORT QDltSegmentedMsg
 {
 public:
diff --git a/qdlt/qdltserialconnection.h b/qdlt/qdltserialconnection.h
@@ -35,6 +35,16 @@
 
 class QSerialPort;
 
+/**
+ * Represents a serial connection for the purposes of the UI.
+ *
+ * Currently set up as an inheritance scheme - QDltConnection (if necessary at all)
+ * should be an interface.
+ *
+ * @see QDltIPConnection 
+ * @see QDltTCPConnection
+ * @see QDltUDPConnection
+ */
 class QDLT_EXPORT QDltSerialConnection : public QDltConnection
 {
 public:
diff --git a/qdlt/qdltsettingsmanager.h b/qdlt/qdltsettingsmanager.h
@@ -30,6 +30,9 @@
 
 #define DEFAULT_REFRESH_RATE 20
 
+/**
+ * Application options.
+ */
 class QDLT_EXPORT QDltSettingsManager
 {
 // Singleton pattern
diff --git a/qdlt/qdlttcpconnection.h b/qdlt/qdlttcpconnection.h
diff --git a/qdlt/qdltudpconnection.h b/qdlt/qdltudpconnection.h

Original file line number	Diff line number	Diff line change
`@@ -32,6 +32,9 @@`
`32`	`32`	`#include "export_rules.h"`
`33`	`33`	`#include "qdltmsg.h"`
`34`	`34`
	`35`	`+/**`
	`36`	`+ * Unused.`
	`37`	`+ */`
`35`	`38`	`class QDLT_EXPORT QDltDataView`
`36`	`39`	`{`
`37`	`40`	`public:`
Original file line number	Diff line number	Diff line change
`@@ -32,6 +32,10 @@`
`32`	`32`
`33`	`33`	`#include "export_rules.h"`
`34`	`34`
	`35`	`+/**`
	`36`	`+ * This class contains various functions relevant to the UI,`
	`37`	`+ * corresponding to user commands.`
	`38`	`+ */`
`35`	`39`	`class QDLT_EXPORT QDltControl : public QObject`
`36`	`40`	`{`
`37`	`41`	`Q_OBJECT`