Doc: improved for class Adapter::Session

src/Adapter.hh

@@ -53,22 +53,50 @@ namespace pEp {
         // returns the thread id of the sync thread
         std::thread::id sync_thread_id();
 
+
+        // The thread-local pEp-session
+        // CAVEAT: there is a default constructor Sesssion(),
+        // BUT
+        // the session object needs to be initialized in order to be usable.
         class Session {
         public:
-            // TODO: needed because libpEpAdapter provides a static instance
-            // the session needs to be initialized in order to be usable.
             Session();
-            // Init using CallbackDispatcher
-            // CAUTION: This may result in a partially initialized session.
-            // If there are any problem with register_sync_callbacks(), it will still
-            // succeed. (e.g. due to no own identities yet)
+
+            // Initialize()
+            // Initializes the session and registers the CallbackDispatcher as callbacks
+            //
+            // SyncModes sync_mode:
+            // * Sync:
+            // Unbuffered, synchronous execution model. no pEp-sync-thread will be created, or should be created.
+            // The sync-events generated by the engine will be re-injected into the engine straight away.
+            // *  ASync:
+            // Buffered (queue), asynchronous execution model. A pEp-sync-thread will be created, or should be created.
+            // The sync-events generated by the engine are being put into a libpEpAdapter managed queue.
+            // The sync-thread will process the events in the queue and inject it into the state-machine in the engine
+            //
+            // bool adapter_manages_sync_thread:
+            // * true: libpEpAdapter will not manage the sync thread, the adapter impl will have to implement it.
+            // * false: libpEpAdapter will manage the sync thread
+            //
+            // TODO:
+            // CAUTION: This call may result in a partially initialized session,
+            // If there are any problems with register_sync_callbacks()
+            // (e.g. due to no own identities yet)
+            // it will still succeed.
             // BUT
             // * Sync will not work
             // * Group Encryption will not work
-            // TODO: This needs to be resolved in the engine, new func register_callbacks()
-            // that is not sync specific, and move the sync-checks to "start-sync()"
-            void initialize(SyncModes sync_mode = SyncModes::Async, bool adapter_manages_sync_thread = false);
-            // Arbitrary callbacks
+            // TODO: This needs to be resolved in the engine, by creating a
+            //  new func register_callbacks() that is not sync specific,
+            //  and move the sync-checks to "start-sync()".
+            // Current workaround: a warning is printed out in this case
+            void initialize(
+                SyncModes sync_mode = SyncModes::Async,
+                bool adapter_manages_sync_thread = false);
+
+            // initialize()
+            // Same as the initialize() method above, but you can specify arbitrary callbacks
+            // to be registered.
             void initialize(
                 SyncModes sync_mode,
                 bool adapter_manages_sync_thread,
@@ -80,7 +108,7 @@ namespace pEp {
 
             // Not copyable
             Session(const Session &) = delete;
-            Session operator=(const Session&) = delete;
+            Session operator=(const Session &) = delete;
 
             void release();
             PEP_SESSION operator()();