From 3376f7fa374d17a78e295e2d24a9762b70e8b64d Mon Sep 17 00:00:00 2001
From: Dhanya Thattil <dhanya.thattil@psi.ch>
Date: Mon, 14 Sep 2020 15:39:21 +0200
Subject: [PATCH] wip, doc

---
 python/slsdet/detector.py              | 11 +++++++++++
 slsDetectorSoftware/include/Detector.h |  6 ++++--
 slsDetectorSoftware/src/CmdProxy.cpp   | 10 +++++++++-
 3 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/python/slsdet/detector.py b/python/slsdet/detector.py
index a89da6f0b..d5362bd98 100755
--- a/python/slsdet/detector.py
+++ b/python/slsdet/detector.py
@@ -174,6 +174,7 @@ class Detector(CppDetectorApi):
 
     @property
     def clientversion(self):
+        """Client software version in format [YYMMDD]"""
         return self.getClientVersion()
 
     @property
@@ -1256,6 +1257,16 @@ class Detector(CppDetectorApi):
     def acquire(self):
         """
         Run the configured measurement
+        Note
+        ----
+        Blocking command, where control server is blocked and cannot accept other commands until acquisition is done. \n
+        - sets acquiring flag
+        - starts the receiver listener (if enabled)
+        - starts detector acquisition for number of frames set
+        - monitors detector status from running to idle
+        - stops the receiver listener (if enabled)
+        - increments file index if file write enabled
+        - resets acquiring flag
         """
         super().acquire()
         print('\n', end = '')
diff --git a/slsDetectorSoftware/include/Detector.h b/slsDetectorSoftware/include/Detector.h
index 366b8d00e..08bd1d1bd 100644
--- a/slsDetectorSoftware/include/Detector.h
+++ b/slsDetectorSoftware/include/Detector.h
@@ -424,12 +424,14 @@ class Detector {
     /**
      * Blocking call: Acquire the number of frames set
      * - sets acquiring flag
-     * - starts the receiver listener
+     * - starts the receiver listener (if enabled)
      * - starts detector acquisition for number of frames set
      * - monitors detector status from running to idle
-     * - stops the receiver listener
+     * - stops the receiver listener (if enabled)
      * - increments file index if file write enabled
      * - resets acquiring flag
+     * Control server is blocked and cannot accept other commands until
+     * acquisition is done.
      */
     void acquire();
 
diff --git a/slsDetectorSoftware/src/CmdProxy.cpp b/slsDetectorSoftware/src/CmdProxy.cpp
index 54f9a4b43..31801dec9 100644
--- a/slsDetectorSoftware/src/CmdProxy.cpp
+++ b/slsDetectorSoftware/src/CmdProxy.cpp
@@ -182,7 +182,15 @@ std::string CmdProxy::VirtualServer(int action) {
 std::string CmdProxy::Acquire(int action) {
     std::ostringstream os;
     if (action == defs::HELP_ACTION) {
-        os << cmd << "\n\tAcquire the number of frames set up.\n";
+        os << cmd
+           << "\n\tAcquire the number of frames set up.\n\tBlocking command, "
+              "where control server is blocked and cannot accept other "
+              "commands until acquisition is done. \n\t- sets acquiring "
+              "flag\n\t- starts the receiver listener (if enabled)\n\t- starts "
+              "detector acquisition for number of frames set\n\t- monitors "
+              "detector status from running to idle\n\t- stops the receiver "
+              "listener (if enabled)\n\t- increments file index if file write "
+              "enabled\n\t- resets acquiring flag";
     } else {
         if (det->empty()) {
             throw sls::RuntimeError(