From 7d8accd983db45a3aef4eac360151d91a52d5a77 Mon Sep 17 00:00:00 2001
From: heck <heck@pep.foundation>
Date: Fri, 20 Jan 2023 16:19:52 +0530
Subject: [PATCH] formatting and comments only

---
 src/Adapter.cc  |  4 +++-
 src/Adapter.hh  | 12 ++++++++----
 src/Adapter.hxx | 25 ++++++++-----------------
 3 files changed, 19 insertions(+), 22 deletions(-)

diff --git a/src/Adapter.cc b/src/Adapter.cc
index d15372e..347aaed 100644
--- a/src/Adapter.cc
+++ b/src/Adapter.cc
@@ -82,6 +82,7 @@ namespace pEp {
         {
         }
 
+        // Public/Static
         void Session::initialize(SyncModes sync_mode, bool adapter_manages_sync_thread)
         {
             pEpLog("Initializing session with CallbackDispatcher...");
@@ -92,6 +93,7 @@ namespace pEp {
                 adapter_manages_sync_thread);
         }
 
+        // Public/Static
         void Session::initialize(
             SyncModes sync_mode,
             bool adapter_manages_sync_thread,
@@ -102,6 +104,7 @@ namespace pEp {
             _init(messageToSend, notifyHandshake, sync_mode, adapter_manages_sync_thread);
         }
 
+        // Private/Static
         void Session::_init(
             ::messageToSend_t messageToSend,
             ::notifyHandshake_t notifyHandshake,
@@ -201,7 +204,6 @@ namespace pEp {
         }
 
         // public
-        // Works even if adapter is managing sync thread, BUT must be using this queue
         bool in_shutdown()
         {
             SYNC_EVENT ev{ nullptr };
diff --git a/src/Adapter.hh b/src/Adapter.hh
index ccaae8c..ba07308 100644
--- a/src/Adapter.hh
+++ b/src/Adapter.hh
@@ -15,9 +15,7 @@
 
 namespace pEp {
     namespace Adapter {
-        // public
-        enum class SyncModes
-        {
+        enum class SyncModes {
             Sync,
             Async
         };
@@ -46,6 +44,9 @@ namespace pEp {
         // CAVEAT: there is a default constructor Sesssion(),
         // BUT
         // the session object needs to be initialized in order to be usable.
+        // The initialization defines the session configuration for all sessions that
+        // are being created in the lifetime of a process
+        // A Session object is not copyable/assignable
 
         // TODO: remove initialize() and do that in the ctor's
         // remove release() and do that in the destructor
@@ -58,8 +59,9 @@ namespace pEp {
             Session operator=(const Session &) = delete;
             Session operator=(const Session &&) = delete;
             ~Session() = default;
+
             // Initialize()
-            // Initializes the session and registers the CallbackDispatcher as callbacks
+            // Initializes the session and registers the CallbackDispatcher's functions for callbacks
             //
             // SyncModes sync_mode:
             // * Sync:
@@ -103,6 +105,8 @@ namespace pEp {
             void refresh();
 
             void release();
+
+            // returns the PEP_SESSION handle
             PEP_SESSION operator()();
 
             SyncModes _sync_mode;
diff --git a/src/Adapter.hxx b/src/Adapter.hxx
index 8dac021..5e3e010 100644
--- a/src/Adapter.hxx
+++ b/src/Adapter.hxx
@@ -15,7 +15,6 @@ namespace pEp {
         using std::function;
 
         extern std::thread _sync_thread;
-
         extern ::utility::locked_queue<::SYNC_EVENT, ::free_Sync_event> sync_evt_q;
         extern std::mutex mut;
 
@@ -28,11 +27,10 @@ namespace pEp {
          * Sync Thread
          * 1. Execute registered startup function
          * 2. Create session for the sync thread (registers: messageToSend, inject_sync_event, ensure_passphrase)
-         * 3. register_sync_callbacks() (registers: _notifyHandshake, _retrieve_next_sync_event)
-         * 4. Enter Sync Event Dispatching Loop (do_sync_protocol())
-         * 5. unregister_sync_callbacks()
-         * 6. Release the session
-         * 7. Execute registered shutdown function
+         * 3. Enter Sync Event Processing Loop (do_sync_protocol())
+         * 4. unregister_sync_callbacks()
+         * 5. Release the session
+         * 6. Execute registered shutdown function
          */
         // private
         template<class T>
@@ -71,29 +69,22 @@ namespace pEp {
             }
 
             pEpLog("sync protocol loop started");
-            // 4. Enter Sync Event Dispatching Loop (do_sync_protocol())
             ::do_sync_protocol(session(), (void *)obj);
             pEpLog("sync protocol loop ended");
 
-            // 5. unregister_sync_callbacks()
+            // 4. unregister_sync_callbacks()
             unregister_sync_callbacks(session());
 
-            // 6. Release the session
+            // 5. Release the session
             session.release();
 
-            // 7. Execute registered shutdown function
+            // 6. Execute registered shutdown function
             if (obj && _shutdown) {
                 _shutdown(obj);
             }
         }
 
-        /*
-         * Sync Thread Startup
-         * 1. throw if main thread session is not initialized
-         * 2. Start the sync thread
-         * 3. Defer execution until sync thread register_sync_callbacks() has returned
-         * 4. Throw pending exception from the sync thread
-         */
+        // Sync Thread Startup
         // private
         template<class T>
         void startup(T *obj, std::function<void(T *)> _startup, std::function<void(T *)> _shutdown)