refactor: little fixes and reorganizations around Connection class

include/sdbus-c++/IConnection.h

@@ -166,6 +166,12 @@ namespace sdbus {
          * the connection. This is a convenient way to interrogate a connection
          * to see what objects it has.
          *
+         * This call creates a floating registration. The ObjectManager will
+         * be there for the object path until the connection is destroyed.
+         *
+         * Another, recommended way to add object managers is directly through
+         * IObject API.
+         *
          * @throws sdbus::Error in case of failure
          */
         virtual void addObjectManager(const std::string& objectPath) = 0;

include/sdbus-c++/Message.h

@@ -32,7 +32,6 @@
 #include <string>
 #include <vector>
 #include <map>
-#include <memory>
 #include <utility>
 #include <cstdint>
 #include <cassert>
@@ -55,16 +54,11 @@ namespace sdbus {
 
 namespace sdbus {
 
-    // Assume the caller has already obtained message ownership
-    struct adopt_message_t { explicit adopt_message_t() = default; };
-    inline constexpr adopt_message_t adopt_message{};
-
     /********************************************//**
      * @class Message
      *
      * Message represents a D-Bus message, which can be either method call message,
-     * method reply message, signal message, or a plain message serving as a storage
-     * for serialized data.
+     * method reply message, signal message, or a plain message.
      *
      * Serialization and deserialization functions are provided for types supported
      * by D-Bus.
@@ -173,17 +167,12 @@ namespace sdbus {
         mutable bool ok_{true};
     };
 
-    struct dont_request_slot_t { explicit dont_request_slot_t() = default; };
-    inline constexpr dont_request_slot_t dont_request_slot{};
-
     class MethodCall : public Message
     {
         using Message::Message;
         friend Factory;
 
     public:
-        using Slot = std::unique_ptr<void, std::function<void(void*)>>;
-
         MethodCall() = default;
 
         MethodReply send(uint64_t timeout) const;
@@ -244,6 +233,7 @@ namespace sdbus {
         PropertyGetReply() = default;
     };
 
+    // Represents any of the above message types, or just a message that serves as a container for data
     class PlainMessage : public Message
     {
         using Message::Message;

include/sdbus-c++/TypeTraits.h

@@ -33,6 +33,7 @@
 #include <map>
 #include <cstdint>
 #include <functional>
+#include <memory>
 #include <tuple>
 
 // Forward declarations
@@ -53,12 +54,30 @@ namespace sdbus {
 
 namespace sdbus {
 
+    // Callbacks from sdbus-c++
     using method_callback = std::function<void(MethodCall msg)>;
     using async_reply_handler = std::function<void(MethodReply& reply, const Error* error)>;
     using signal_handler = std::function<void(Signal& signal)>;
     using property_set_callback = std::function<void(PropertySetCall& msg)>;
     using property_get_callback = std::function<void(PropertyGetReply& reply)>;
 
+    // Type-erased RAII-style handle to callbacks/subscriptions registered to sdbus-c++
+    using Slot = std::unique_ptr<void, std::function<void(void*)>>;
+
+    // Tag specifying that an owning slot handle shall be returned from the function
+    struct request_slot_t { explicit request_slot_t() = default; };
+    inline constexpr request_slot_t request_slot{};
+    // Tag specifying that the library shall own the slot resulting from the call of the function (so-called floating slot)
+    struct dont_request_slot_t { explicit dont_request_slot_t() = default; };
+    inline constexpr dont_request_slot_t dont_request_slot{};
+    // Tag denoting the assumption that the caller has already obtained message ownership
+    struct adopt_message_t { explicit adopt_message_t() = default; };
+    inline constexpr adopt_message_t adopt_message{};
+    // Tag denoting the assumption that the caller has already obtained fd ownership
+    struct adopt_fd_t { explicit adopt_fd_t() = default; };
+    inline constexpr adopt_fd_t adopt_fd{};
+
+    // Template specializations for getting D-Bus signatures from C++ types
     template <typename _T>
     struct signature_of
     {

include/sdbus-c++/Types.h

@@ -185,9 +185,6 @@ namespace sdbus {
         using std::string::operator=;
     };
 
-    struct adopt_fd_t { explicit adopt_fd_t() = default; };
-    inline constexpr adopt_fd_t adopt_fd{};
-
     /********************************************//**
      * @struct UnixFd
      *