From ace91efdb5ebc0099c3ede3d7acf011f80afbd30 Mon Sep 17 00:00:00 2001
From: Patric Stout <github@truebrain.nl>
Date: Sun, 11 Sep 2022 15:25:39 +0200
Subject: [PATCH] chore(interface): document behaviour of overlapping subscriptions

---
 example/pubsub/main.cpp |  6 +++++-
 include/TrueMQTT.h      | 16 ++++++++++++----
 2 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/example/pubsub/main.cpp b/example/pubsub/main.cpp
index 30cd041..46b9bf3 100644
--- a/example/pubsub/main.cpp
+++ b/example/pubsub/main.cpp
@@ -30,6 +30,10 @@ int main()
                      {
         std::cout << "Received message on exact topic " << topic << ": " << payload << std::endl;
         stop++; });
+    client.subscribe("test/test/test", [&stop](const std::string topic, const std::string payload)
+                     {
+        std::cout << "Received message on exact topic " << topic << ": " << payload << std::endl;
+        stop++; });
     client.subscribe("test/+/test", [&stop](const std::string topic, const std::string payload)
                      {
         std::cout << "Received message on single wildcard topic " << topic << ": " << payload << std::endl;
@@ -48,7 +52,7 @@ int main()
     client.publish("test/test/test", "Hello World!", false);
 
     // Wait till we receive the message back on our subscription.
-    while (stop != 3)
+    while (stop < 4)
     {
         std::this_thread::sleep_for(std::chrono::milliseconds(10));
     }
diff --git a/include/TrueMQTT.h b/include/TrueMQTT.h
index 5ebd705..187e074 100644
--- a/include/TrueMQTT.h
+++ b/include/TrueMQTT.h
@@ -233,10 +233,18 @@ namespace TrueMQTT
          * @param topic The topic to subscribe to.
          * @param callback The callback to call when a message arrives on this topic.
          *
-         * @note Subscription can overlap, but you cannot subscribe on the exact same topic twice.
-         * If you do, the callback of the first subscription will be overwritten.
-         * In other words, "a/+" and "a/b" is fine, and callbacks for both subscribes will be
-         * called when something is published on "a/b".
+         * @note Subscription can overlap, even on the exact same topic. All callbacks that
+         * match the topic will be called.
+         * @note Depending on the broker, overlapping subscriptions can trigger one or more
+         * calls to the same callback with the same message. This is because some brokers
+         * send the message to all matching subscriptions, and some only send it to one.
+         * To prevent some callbacks not being called for brokers that do the latter, this
+         * library will call all matching callbacks every time.
+         * Example: If you subscribe to "a/b" and "a/+", and a message arrives on "a/b",
+         * both callbacks will be called. Some brokers will send a single message when
+         * someone publishes to "a/b", and some will send for every subscription matching
+         * (so twice in this case). In the latter case, the callback of both "a/b" and "a/+"
+         * are called twice with the same "a/b" message.
          * @note You cannot subscribe a topic if you are disconnected from the broker. Call
          * \ref connect first.
          * @note This function can stall for a short moment if you publish just at the
--
libgit2 0.21.4