Add documentation

client/client_connection.hpp

@@ -153,6 +153,7 @@ class ClientConnection
     virtual void getNextMessage(const MessageHandler<msg::BaseMessage>& handler) = 0;
 
 protected:
+    /// Send @p buffer, return result in @p write_handler
     virtual void write(boost::asio::streambuf& buffer, WriteHandler&& write_handler) = 0;
 
     /// Connect to @p endpoint

client/controller.cpp

@@ -129,7 +129,7 @@ Controller::Controller(boost::asio::io_context& io_context, const ClientSettings
 #endif // HAS_OPENSSL
 }
 
-
+/// Helper to create a player instance
 template <typename PlayerType>
 std::unique_ptr<Player> Controller::createPlayer(ClientSettings::Player& settings, const std::string& player_name)
 {

client/double_buffer.hpp

@@ -1,6 +1,6 @@
 /***
     This file is part of snapcast
-    Copyright (C) 2014-2024  Johannes Pohl
+    Copyright (C) 2014-2025  Johannes Pohl
 
     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
@@ -36,25 +36,28 @@ template <class T>
 class DoubleBuffer
 {
 public:
-    DoubleBuffer(size_t size = 10) : bufferSize(size)
+    /// c'tor
+    explicit DoubleBuffer(size_t size = 10) : bufferSize(size)
     {
     }
 
+    /// Add @p element, pop last, if buffer is full
     inline void add(const T& element)
     {
         buffer.push_back(element);
         if (buffer.size() > bufferSize)
             buffer.pop_front();
     }
 
+    /// Add @p element, pop last, if buffer is full
     inline void add(T&& element)
     {
         buffer.push_back(std::move(element));
         if (buffer.size() > bufferSize)
             buffer.pop_front();
     }
 
-    /// Median as mean over N values around the median
+    /// @return median as mean over N values around the median
     T median(uint16_t mean = 1) const
     {
         if (buffer.empty())
@@ -78,6 +81,7 @@ class DoubleBuffer
         }
     }
 
+    /// @return mean value
     double mean() const
     {
         if (buffer.empty())
@@ -88,6 +92,7 @@ class DoubleBuffer
         return mean;
     }
 
+    /// @return @p percentile percentile
     T percentile(unsigned int percentile) const
     {
         if (buffer.empty())
@@ -97,6 +102,7 @@ class DoubleBuffer
         return tmpBuffer[(size_t)((tmpBuffer.size() - 1) * ((float)percentile / (float)100))];
     }
 
+    /// @return array of different percentiles
     template <std::size_t Size>
     std::array<T, Size> percentiles(std::array<uint8_t, Size> percentiles) const
     {
@@ -112,31 +118,37 @@ class DoubleBuffer
         return result;
     }
 
+    /// @return if the buffer is full
     inline bool full() const
     {
         return (buffer.size() == bufferSize);
     }
 
+    /// Clear the buffer
     inline void clear()
     {
         buffer.clear();
     }
 
+    /// @return current size of the buffer
     inline size_t size() const
     {
         return buffer.size();
     }
 
+    /// @return if the buffer is empty
     inline bool empty() const
     {
         return buffer.empty();
     }
 
+    /// Set size of the buffer
     void setSize(size_t size)
     {
         bufferSize = size;
     }
 
+    /// @return the raw buffer
     const std::deque<T>& getBuffer() const
     {
         return buffer;

client/stream.hpp

@@ -45,11 +45,14 @@
 class Stream
 {
 public:
+    /// c'tor
     Stream(const SampleFormat& in_format, const SampleFormat& out_format);
+    /// d'tor
     virtual ~Stream() = default;
 
     /// Adds PCM data to the queue
     void addChunk(std::unique_ptr<msg::PcmChunk> chunk);
+    /// Remove all chunks from the queue
     void clearChunks();
 
     /// Get PCM data, which will be played out in "outputBufferDacTime" time
@@ -68,11 +71,13 @@ class Stream
     /// "Server buffer": playout latency, e.g. 1000ms
     void setBufferLen(size_t bufferLenMs);
 
+    /// @return sampleformat
     const SampleFormat& getFormat() const
     {
         return format_;
     }
 
+    /// @return if chunk was avabilable within @p timeout
     bool waitForChunk(const std::chrono::milliseconds& timeout) const;
 
 private:

common/queue.hpp

@@ -30,6 +30,12 @@ template <typename T>
 class Queue
 {
 public:
+    /// c'tor
+    Queue() = default;
+    Queue(const Queue&) = delete;            ///< disable copying
+    Queue& operator=(const Queue&) = delete; ///< disable assignment
+
+    /// @return next element, delete from queue
     T pop()
     {
         std::unique_lock<std::mutex> mlock(mutex_);
@@ -41,6 +47,7 @@ class Queue
         return val;
     }
 
+    /// abort wait
     void abort_wait()
     {
         {
@@ -50,6 +57,7 @@ class Queue
         cond_.notify_one();
     }
 
+    /// wait for @timeout for new element, @return if an element has been added
     bool wait_for(const std::chrono::microseconds& timeout) const
     {
         std::unique_lock<std::mutex> mlock(mutex_);
@@ -60,6 +68,7 @@ class Queue
         return !queue_.empty() && !abort_;
     }
 
+    /// @return if an element has been returned in @p item within @p timeout
     bool try_pop(T& item, const std::chrono::microseconds& timeout = std::chrono::microseconds(0))
     {
         std::unique_lock<std::mutex> mlock(mutex_);
@@ -79,6 +88,7 @@ class Queue
         return true;
     }
 
+    /// return next element in @p item, wait for an element if queue is empty
     void pop(T& item)
     {
         std::unique_lock<std::mutex> mlock(mutex_);
@@ -89,6 +99,7 @@ class Queue
         queue_.pop_front();
     }
 
+    /// Add @p item to the queue
     void push_front(const T& item)
     {
         {
@@ -98,6 +109,7 @@ class Queue
         cond_.notify_one();
     }
 
+    /// return a copy of the next element in @p copy, @return false if the queue is empty
     bool back_copy(T& copy)
     {
         std::lock_guard<std::mutex> mlock(mutex_);
@@ -107,6 +119,7 @@ class Queue
         return true;
     }
 
+    /// return a copy of the last element in @p copy, @return false if the queue is empty
     bool front_copy(T& copy)
     {
         std::lock_guard<std::mutex> mlock(mutex_);
@@ -116,6 +129,7 @@ class Queue
         return true;
     }
 
+    /// Add element @p item at the front of the queue
     void push_front(T&& item)
     {
         {
@@ -125,6 +139,7 @@ class Queue
         cond_.notify_one();
     }
 
+    /// Add element @p item at the end of the queue
     void push(const T& item)
     {
         {
@@ -134,6 +149,7 @@ class Queue
         cond_.notify_one();
     }
 
+    /// Add element @p item at the end of the queue
     void push(T&& item)
     {
         {
@@ -143,21 +159,19 @@ class Queue
         cond_.notify_one();
     }
 
+    /// @return number of elements in the queue
     size_t size() const
     {
         std::lock_guard<std::mutex> mlock(mutex_);
         return queue_.size();
     }
 
+    /// @return if the queue is empty
     bool empty() const
     {
         return (size() == 0);
     }
 
-    Queue() = default;
-    Queue(const Queue&) = delete;            // disable copying
-    Queue& operator=(const Queue&) = delete; // disable assignment
-
 private:
     std::deque<T> queue_;
     mutable std::atomic<bool> abort_;

common/resampler.cpp

@@ -1,6 +1,6 @@
 /***
     This file is part of snapcast
-    Copyright (C) 2014-2024  Johannes Pohl
+    Copyright (C) 2014-2025  Johannes Pohl
 
     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
@@ -21,7 +21,9 @@
 
 // local headers
 #include "common/aixlog.hpp"
+#ifndef HAS_SOXR
 #include "common/snap_exception.hpp"
+#endif
 
 // standard headers
 #include <cmath>
@@ -195,7 +197,7 @@ std::shared_ptr<msg::PcmChunk> Resampler::resample(const msg::PcmChunk& chunk)
 }
 
 
-shared_ptr<msg::PcmChunk> Resampler::resample(shared_ptr<msg::PcmChunk> chunk)
+std::shared_ptr<msg::PcmChunk> Resampler::resample(std::shared_ptr<msg::PcmChunk> chunk)
 {
 #ifndef HAS_SOXR
     return chunk;

common/sample_format.hpp

@@ -38,57 +38,70 @@
 class SampleFormat
 {
 public:
+    /// c'tor
     SampleFormat();
+    /// c'tor
     SampleFormat(const std::string& format);
+    /// c'tor
     SampleFormat(uint32_t rate, uint16_t bits, uint16_t channels);
 
+    /// @return sampleformat as string rate:bits::channels
     std::string toString() const;
 
+    /// Set @p format (rate:bits::channels)
     void setFormat(const std::string& format);
+    /// Set format
     void setFormat(uint32_t rate, uint16_t bits, uint16_t channels);
 
+    /// @return if has format
     bool isInitialized() const
     {
         return ((rate_ != 0) || (bits_ != 0) || (channels_ != 0));
     }
 
+    /// @return rate
     uint32_t rate() const
     {
         return rate_;
     }
 
+    /// @return bits
     uint16_t bits() const
     {
         return bits_;
     }
 
+    /// @return channels
     uint16_t channels() const
     {
         return channels_;
     }
 
-    // size in [bytes] of a single mono sample, e.g. 2 bytes (= 16 bits)
+    /// @return size in [bytes] of a single mono sample, e.g. 2 bytes (= 16 bits)
     uint16_t sampleSize() const
     {
         return sample_size_;
     }
 
-    // size in [bytes] of a frame (sum of sample sizes = #channel*sampleSize), e.g. 4 bytes (= 2 channel * 16 bit)
+    /// @return size in [bytes] of a frame (sum of sample sizes = #channel*sampleSize), e.g. 4 bytes (= 2 channel * 16 bit)
     uint16_t frameSize() const
     {
         return frame_size_;
     }
 
+    /// @return rate per ms (= rate / 1000)
     inline double msRate() const
     {
         return static_cast<double>(rate_) / 1000.;
     }
 
+    /// @return rate per micro seconds (= rate / 1000000)
     inline double usRate() const
     {
         return static_cast<double>(rate_) / 1000000.;
     }
 
+    /// @return rate per nano seconds (= rate / 1000000000)
     inline double nsRate() const
     {
         return static_cast<double>(rate_) / 1000000000.;

server/authinfo.hpp

@@ -79,7 +79,7 @@ class AuthInfo
 
     /// Authenticate with basic scheme
     ErrorCode authenticateBasic(const std::string& credentials);
-    /// Authenticate with <user>:<password>
+    /// Authenticate with user:password
     ErrorCode authenticatePlain(const std::string& user_password);
     /// Authenticate with bearer scheme
     // ErrorCode authenticateBearer(const std::string& token);
@@ -88,7 +88,7 @@ class AuthInfo
     /// Authenticate with scheme ("basic" or "bearer") and auth param
     ErrorCode authenticate(const std::string& scheme, const std::string& param);
 
-    /// @return JWS token for @p username and @p password
+    // @return JWS token for @p username and @p password
     // ErrorOr<std::string> getToken(const std::string& username, const std::string& password) const;
     /// @return if the authenticated user has permission to access @p ressource
     bool hasPermission(const std::string& resource) const;

server/control_server.cpp

@@ -146,7 +146,7 @@ void ControlServer::onMessageReceived(std::shared_ptr<ControlSession> session, c
 }
 
 
-void ControlServer::onNewSession(shared_ptr<ControlSession> session)
+void ControlServer::onNewSession(std::shared_ptr<ControlSession> session)
 {
     std::lock_guard<std::recursive_mutex> mlock(session_mutex_);
     session->start();

server/encoder/flac_encoder.hpp

@@ -25,6 +25,7 @@
 #include "FLAC/stream_encoder.h"
 
 // standard headers
+#include <array>
 #include <cstdio>
 #include <cstdlib>
 #include <cstring>