Add some documentation

.github/workflows/ci.yml

@@ -75,7 +75,7 @@ jobs:
           mkdir -p build/doxygen
           doxygen 2>&1 | tee build/doxygen.log
           WARNINGS=$(cat build/doxygen.log | sort | uniq | grep -e ": warning: " | wc -l)
-          MAX_ALLOWED=840
+          MAX_ALLOWED=775
           echo "Doxygen finished with $WARNINGS warnings, max allowed: $MAX_ALLOWED"
           if [ "$WARNINGS" -gt "$MAX_ALLOWED" ]; then exit $WARNINGS; else exit 0; fi;
 

common/message/message.hpp

@@ -44,15 +44,18 @@ class vectorwrapbuf : public std::basic_streambuf<CharT, TraitsT>
 };
 */
 
+// https://stackoverflow.com/questions/7781898/get-an-istream-from-a-char
+/// Helper to convert char* to a stream buffer
 struct membuf : public std::basic_streambuf<char>
 {
+    /// c'tor
     membuf(char* begin, char* end)
     {
         this->setg(begin, begin, end);
     }
 };
 
-
+/// Message type enums
 enum class message_type : uint16_t
 {
     kBase = 0,
@@ -68,6 +71,7 @@ enum class message_type : uint16_t
     kLast = kClientInfo
 };
 
+/// Message type to string
 static std::ostream& operator<<(std::ostream& os, const message_type& msg_type)
 {
     switch (msg_type)
@@ -99,21 +103,29 @@ static std::ostream& operator<<(std::ostream& os, const message_type& msg_type)
     return os;
 }
 
+/// Timeval like struct
 struct tv
 {
+    /// c'tor
     tv()
     {
         timeval t;
         chronos::steadytimeofday(&t);
         sec = t.tv_sec;
         usec = t.tv_usec;
     }
+
+    /// C'tor, construct from timeval @p tv
     tv(timeval tv) : sec(tv.tv_sec), usec(tv.tv_usec){};
+    /// C'tor, construct from @p _sec and @p _usec
     tv(int32_t _sec, int32_t _usec) : sec(_sec), usec(_usec){};
 
+    /// seconds
     int32_t sec;
+    /// micro seconds
     int32_t usec;
 
+    /// add another tv
     tv operator+(const tv& other) const
     {
         tv result(*this);
@@ -127,6 +139,7 @@ struct tv
         return result;
     }
 
+    /// subtract another tv
     tv operator-(const tv& other) const
     {
         tv result(*this);
@@ -144,24 +157,30 @@ struct tv
 namespace msg
 {
 
+/// Max message size = 1mb
 const size_t max_size = 1000000;
 
 struct BaseMessage;
 
 using message_ptr = std::shared_ptr<msg::BaseMessage>;
 
+/// Base message with common message header for all messages
 struct BaseMessage
 {
+    /// c'tor
     BaseMessage() : BaseMessage(message_type::kBase)
     {
     }
 
+    /// c'tor with message type @p type_
     BaseMessage(message_type type_) : type(type_), id(0), refersTo(0), size(0)
     {
     }
 
+    /// d'tor
     virtual ~BaseMessage() = default;
 
+    /// Deserialize message from @p stream
     virtual void read(std::istream& stream)
     {
         readVal(stream, type);
@@ -174,13 +193,15 @@ struct BaseMessage
         readVal(stream, size);
     }
 
+    /// Deserialize message from @p payload buffer
     void deserialize(char* payload)
     {
         membuf databuf(payload, payload + BaseMessage::getSize());
         std::istream is(&databuf);
         read(is);
     }
 
+    /// Deserialize message from message header @p baseMessage and message @p payload
     void deserialize(const BaseMessage& baseMessage, char* payload)
     {
         type = baseMessage.type;
@@ -194,6 +215,7 @@ struct BaseMessage
         read(is);
     }
 
+    /// Serialize message to @p stream
     virtual void serialize(std::ostream& stream) const
     {
         writeVal(stream, type);
@@ -208,127 +230,151 @@ struct BaseMessage
         doserialize(stream);
     }
 
+    /// @return binary size of the base message
     virtual uint32_t getSize() const
     {
         return 3 * sizeof(uint16_t) + 2 * sizeof(tv) + sizeof(uint32_t);
     };
 
+    /// the message type
     message_type type;
+    /// the message id, used to correlate request and response
     mutable uint16_t id;
+    /// a response message might refer to the message id of the request
     uint16_t refersTo;
+    /// timestamp when the message has been received
     tv received;
+    /// timestamp when the message was sent
     mutable tv sent;
+    /// the payload size
     mutable uint32_t size;
 
 protected:
+    /// serialize a bool @p val to @p stream
     void writeVal(std::ostream& stream, const bool& val) const
     {
         char c = val ? 1 : 0;
         writeVal(stream, c);
     }
 
+    /// serialize a const char* @p val to @p stream
     void writeVal(std::ostream& stream, const char& val) const
     {
         stream.write(reinterpret_cast<const char*>(&val), sizeof(char));
     }
 
+    /// serialize an uint16 @p val to @p stream
     void writeVal(std::ostream& stream, const uint16_t& val) const
     {
         uint16_t v = SWAP_16(val);
         stream.write(reinterpret_cast<const char*>(&v), sizeof(uint16_t));
     }
 
+    /// serialize the message type @p val to @p stream
     void writeVal(std::ostream& stream, const message_type& val) const
     {
         uint16_t v = SWAP_16(static_cast<uint16_t>(val));
         stream.write(reinterpret_cast<const char*>(&v), sizeof(uint16_t));
     }
 
+    /// serialize an int16 @p val to @p stream
     void writeVal(std::ostream& stream, const int16_t& val) const
     {
         uint16_t v = SWAP_16(val);
         stream.write(reinterpret_cast<const char*>(&v), sizeof(int16_t));
     }
 
+    /// serialize an uint32 @p val to @p stream
     void writeVal(std::ostream& stream, const uint32_t& val) const
     {
         uint32_t v = SWAP_32(val);
         stream.write(reinterpret_cast<const char*>(&v), sizeof(uint32_t));
     }
 
+    /// serialize an int32 @p val to @p stream
     void writeVal(std::ostream& stream, const int32_t& val) const
     {
         uint32_t v = SWAP_32(val);
         stream.write(reinterpret_cast<const char*>(&v), sizeof(int32_t));
     }
 
+    /// serialize a char* string @p payload of @p size to @p stream
     void writeVal(std::ostream& stream, const char* payload, const uint32_t& size) const
     {
         writeVal(stream, size);
         stream.write(payload, size);
     }
 
+    /// serialize an std::string @p val to @p stream
     void writeVal(std::ostream& stream, const std::string& val) const
     {
         auto len = static_cast<uint32_t>(val.size());
         writeVal(stream, val.c_str(), len);
     }
 
 
-
+    /// Deserialize a bool @p val from @p stream
     void readVal(std::istream& stream, bool& val) const
     {
         char c;
         readVal(stream, c);
         val = (c != 0);
     }
 
+    /// Deserialize a char @p val from @p stream
     void readVal(std::istream& stream, char& val) const
     {
         stream.read(reinterpret_cast<char*>(&val), sizeof(char));
     }
 
+    /// Deserialize an uint16 @p val from @p stream
     void readVal(std::istream& stream, uint16_t& val) const
     {
         stream.read(reinterpret_cast<char*>(&val), sizeof(uint16_t));
         // cppcheck-suppress selfAssignment
         val = SWAP_16(val);
     }
 
+    /// Deserialize a message_type @p val from @p stream
     void readVal(std::istream& stream, message_type& val) const
     {
         stream.read(reinterpret_cast<char*>(&val), sizeof(uint16_t));
         val = static_cast<message_type>(SWAP_16(static_cast<uint16_t>(val)));
     }
 
+    /// Deserialize an int16 @p val from @p stream
     void readVal(std::istream& stream, int16_t& val) const
     {
         stream.read(reinterpret_cast<char*>(&val), sizeof(int16_t));
         // cppcheck-suppress selfAssignment
         val = SWAP_16(val);
     }
 
+    /// Deserialize an uint32 @p val from @p stream
     void readVal(std::istream& stream, uint32_t& val) const
     {
         stream.read(reinterpret_cast<char*>(&val), sizeof(uint32_t));
         // cppcheck-suppress selfAssignment
         val = SWAP_32(val);
     }
 
+    /// Deserialize an int32 @p val from @p stream
     void readVal(std::istream& stream, int32_t& val) const
     {
         stream.read(reinterpret_cast<char*>(&val), sizeof(int32_t));
         // cppcheck-suppress selfAssignment
         val = SWAP_32(val);
     }
 
+    /// Deserialize a char* string @p payload of @p size from @p stream
     void readVal(std::istream& stream, char** payload, uint32_t& size) const
     {
         readVal(stream, size);
         *payload = (char*)realloc(*payload, size);
         stream.read(*payload, size);
     }
 
+    /// Deserialize a std::string @p val from @p stream
     void readVal(std::istream& stream, std::string& val) const
     {
         uint32_t len;
@@ -337,7 +383,7 @@ struct BaseMessage
         stream.read(&val[0], len);
     }
 
-
+    /// Deserialize message to std::ostream
     virtual void doserialize(std::ostream& /*stream*/) const {};
 };