From c49366a54387eae2467db7efd288fd51d8114857 Mon Sep 17 00:00:00 2001
From: Marc Mutz <marc.mutz@qt.io>
Date: Tue, 20 Feb 2024 19:01:00 +0100
Subject: [PATCH] QDBusUtil: document the D-Bus signature grammar

The specification doesn't provide an explicit grammar, so I turned the
prose into ABNF for easier reference.

The goal is both to aid review of the validateSingleType() function
and to eventually use this to write a parser that doesn't use, or at
least limits, recursion.

Pick-to: 6.6 6.5 6.2 5.15
Change-Id: I21f81aa83cde356ab48105ea98f066024e0b7b5e
Reviewed-by: Juha Vuolle <juha.vuolle@qt.io>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
(cherry picked from commit 476d2a7392ee26294d1230f0c5031fe6bb4a0f26)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
---
 src/dbus/qdbusutil.cpp | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/src/dbus/qdbusutil.cpp b/src/dbus/qdbusutil.cpp
index 6a0d546ee42..827418c487e 100644
--- a/src/dbus/qdbusutil.cpp
+++ b/src/dbus/qdbusutil.cpp
@@ -206,6 +206,21 @@ static const char oneLetterTypes[] = "vsogybnqiuxtdh";
 static const char basicTypes[] =      "sogybnqiuxtdh";
 static const char fixedTypes[] =         "ybnqiuxtdh";
 
+/*
+    D-Bus signature grammar (in ABNF), as of 0.42 (2023-08-21):
+    https://dbus.freedesktop.org/doc/dbus-specification.html#type-system
+
+    <signature>            = *<single-complete-type>
+    <single-complete-type> = <basic-type> / <variant> / <struct> / <array>
+    <fixed-type>           = "y" / "b" / "n" / "q" / "i" / "u" / "x" / "t" / "d" / "h"
+    <variable-length-type> = "s" / "o" / "g"
+    <basic-type>           = <variable-length-type> / <fixed-type>
+    <variant>              = "v"
+    <struct>               = "(" 1*<single-complete-type> ")"
+    <array>                = "a" ( <single-complete-type> / <dict-entry> )
+    <dict-entry>           = "{" <basic-type> <single-complete-type> "}"
+*/
+
 static bool isBasicType(int c)
 {
     return c != DBUS_TYPE_INVALID && strchr(basicTypes, c) != nullptr;