add documentation to code

network_io/include/aare/network_io/ZmqHeader.hpp

@@ -98,7 +98,7 @@ struct ZmqHeader {
     /** number of pixels/channels in y axis for this zmq socket */
     uint32_t npixelsy{0};
     /** number of bytes for an image in this socket */
-    uint32_t imageSize{0};
+    uint32_t size{0};
     /** frame number from detector */
     uint64_t acqIndex{0};
     /** frame index (starting at 0 for each acquisition) */

network_io/include/aare/network_io/ZmqSocket.hpp

@@ -10,7 +10,22 @@ class zmq_msg_t;
 
 namespace aare {
 
+/**
+ * @brief parent class for ZmqSocketReceiver and ZmqSocketSender
+ * contains common functions and variables
+ */
 class ZmqSocket {
+  public:
+    ZmqSocket() = default;
+    ~ZmqSocket();
+    ZmqSocket(const ZmqSocket &) = delete;
+    ZmqSocket operator=(const ZmqSocket &) = delete;
+    ZmqSocket(ZmqSocket &&) = delete;
+    void disconnect();
+    void set_zmq_hwm(int hwm);
+    void set_timeout_ms(int n);
+    void set_potential_frame_size(size_t size);
+
   protected:
     void *m_context{nullptr};
     void *m_socket{nullptr};
@@ -20,19 +35,6 @@ class ZmqSocket {
     size_t m_potential_frame_size{1024 * 1024};
     constexpr static size_t m_max_header_size = 1024;
     char *m_header_buffer = new char[m_max_header_size];
-
-  public:
-    ZmqSocket() = default;
-    ~ZmqSocket();
-
-    ZmqSocket(const ZmqSocket &) = delete;
-    ZmqSocket operator=(const ZmqSocket &) = delete;
-    ZmqSocket(ZmqSocket &&) = delete;
-
-    void disconnect();
-    void set_zmq_hwm(int hwm);
-    void set_timeout_ms(int n);
-    void set_potential_frame_size(size_t size);
 };
 
 } // namespace aare

network_io/include/aare/network_io/ZmqSocketReceiver.hpp

@@ -8,14 +8,15 @@
 #include <cstdint>
 #include <string>
 
-// Socket to receive data from a ZMQ publisher
-// needs to be in sync with the main library (or maybe better use the versioning in the header)
-
 // forward declare zmq_msg_t to avoid including zmq.h in the header
 class zmq_msg_t;
 
 namespace aare {
 
+/**
+ * @brief Socket to receive data from a ZMQ publisher
+ * @note needs to be in sync with the main library (or maybe better use the versioning in the header)
+ */
 class ZmqSocketReceiver : public ZmqSocket {
   public:
     ZmqSocketReceiver(const std::string &endpoint);

network_io/include/aare/network_io/ZmqSocketSender.hpp

@@ -5,6 +5,11 @@
 #include "aare/network_io/defs.hpp"
 
 namespace aare {
+
+/**
+ * @brief Socket to send data to a ZMQ subscriber
+ * @note needs to be in sync with the main library (or maybe better use the versioning in the header)
+ */
 class ZmqSocketSender : public ZmqSocket {
   public:
     ZmqSocketSender(const std::string &endpoint);

network_io/src/ZmqHeader.cpp

@@ -77,7 +77,7 @@ std::string ZmqHeader::to_string() const {
     write_digit(s, "ndety", ndety);
     write_digit(s, "npixelsx", npixelsx);
     write_digit(s, "npixelsy", npixelsy);
-    write_digit(s, "imageSize", imageSize);
+    write_digit(s, "size", size);
     write_digit(s, "acqIndex", acqIndex);
     write_digit(s, "frameIndex", frameIndex);
     write_digit(s, "progress", progress);
@@ -117,7 +117,6 @@ void ZmqHeader::from_string(std::string &s) {
 
     for (auto field : object) {
         std::string_view key = field.unescaped_key();
-
         if (key == "data") {
             data = uint64_t(field.value()) ? true : false;
         } else if (key == "jsonversion") {
@@ -134,8 +133,8 @@ void ZmqHeader::from_string(std::string &s) {
             npixelsx = uint32_t(field.value());
         } else if (key == "npixelsy") {
             npixelsy = uint32_t(field.value());
-        } else if (key == "imageSize") {
-            imageSize = uint32_t(field.value());
+        } else if (key == "size") {
+            size = uint32_t(field.value());
         } else if (key == "acqIndex") {
             acqIndex = uint64_t(field.value());
         } else if (key == "frameIndex") {
@@ -187,7 +186,7 @@ void ZmqHeader::from_string(std::string &s) {
 bool ZmqHeader::operator==(const ZmqHeader &other) const {
     return data == other.data && jsonversion == other.jsonversion && dynamicRange == other.dynamicRange &&
            fileIndex == other.fileIndex && ndetx == other.ndetx && ndety == other.ndety && npixelsx == other.npixelsx &&
-           npixelsy == other.npixelsy && imageSize == other.imageSize && acqIndex == other.acqIndex &&
+           npixelsy == other.npixelsy && size == other.size && acqIndex == other.acqIndex &&
            frameIndex == other.frameIndex && progress == other.progress && fname == other.fname &&
            frameNumber == other.frameNumber && expLength == other.expLength && packetNumber == other.packetNumber &&
            detSpec1 == other.detSpec1 && timestamp == other.timestamp && modId == other.modId && row == other.row &&

network_io/src/ZmqSocket.cpp

@@ -3,6 +3,11 @@
 
 namespace aare {
 
+/**
+ * @brief closes the socket and destroys the context
+ * @return void
+ * @note this function is called by the destructor
+ */
 void ZmqSocket::disconnect() {
     zmq_close(m_socket);
     zmq_ctx_destroy(m_context);
@@ -10,6 +15,10 @@ void ZmqSocket::disconnect() {
     m_context = nullptr;
 }
 
+/**
+ * @brief destructor
+ * @note called from child classes (ZmqSocketReceiver and ZmqSocketSender)
+ */
 ZmqSocket::~ZmqSocket() {
     if (m_socket)
         disconnect();

network_io/src/ZmqSocketReceiver.cpp

@@ -79,6 +79,10 @@ int ZmqSocketReceiver::receive_data(std::byte *data, size_t size) {
     return data_bytes_received;
 }
 
+/**
+ * @brief receive a ZmqFrame (header and data)
+ * @return ZmqFrame
+ */
 ZmqFrame ZmqSocketReceiver::receive_zmqframe() {
     // receive header from zmq and parse it
     ZmqHeader header = receive_header();
@@ -94,13 +98,17 @@ ZmqFrame ZmqSocketReceiver::receive_zmqframe() {
     if (bytes_received == -1) {
         throw network_io::NetworkError(LOCATION + "Error receiving frame");
     }
-    if ((uint32_t)bytes_received != header.imageSize) {
+    if ((uint32_t)bytes_received != header.size) {
         throw network_io::NetworkError(
-            fmt::format("{} Expected {} bytes but received {}", LOCATION, header.imageSize, bytes_received));
+            fmt::format("{} Expected {} bytes but received {}", LOCATION, header.size, bytes_received));
     }
     return {header, std::move(frame)};
 }
 
+/**
+ * @brief receive multiple ZmqFrames (header and data)
+ * @return std::vector<ZmqFrame>
+ */
 std::vector<ZmqFrame> ZmqSocketReceiver::receive_n() {
     std::vector<ZmqFrame> frames;
     while (true) {

network_io/test/ZmqHeader.test.cpp

@@ -13,7 +13,7 @@ TEST_CASE("Test ZmqHeader") {
     header.fileIndex = 4;
     header.ndetx = 5;
     header.ndety = 6;
-    header.imageSize = 4800;
+    header.size = 4800;
     header.acqIndex = 8;
     header.frameIndex = 9;
     header.progress = 0.1;
@@ -46,7 +46,7 @@ TEST_CASE("Test ZmqHeader") {
                               "\"ndety\": 6, "
                               "\"npixelsx\": 10, "
                               "\"npixelsy\": 15, "
-                              "\"imageSize\": 4800, "
+                              "\"size\": 4800, "
                               "\"acqIndex\": 8, "
                               "\"frameIndex\": 9, "
                               "\"progress\": 0.100000, "