Add documentation

client/player/alsa_player.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
@@ -44,7 +44,9 @@ static constexpr auto ALSA = "alsa";
 class AlsaPlayer : public Player
 {
 public:
+    /// c'tor
     AlsaPlayer(boost::asio::io_context& io_context, const ClientSettings::Player& settings, std::shared_ptr<Stream> stream);
+    /// d'tor
     ~AlsaPlayer() override;
 
     void start() override;

client/player/coreaudio_player.hpp

@@ -16,8 +16,8 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
 ***/
 
-#ifndef CORE_AUDIO_PLAYER_HPP
-#define CORE_AUDIO_PLAYER_HPP
+
+#pragma once
 
 // local headers
 #include "player.hpp"
@@ -45,10 +45,14 @@ static constexpr auto COREAUDIO = "coreaudio";
 class CoreAudioPlayer : public Player
 {
 public:
+    /// c'tor
     CoreAudioPlayer(boost::asio::io_context& io_context, const ClientSettings::Player& settings, std::shared_ptr<Stream> stream);
+    /// d'tor
     virtual ~CoreAudioPlayer();
 
+    /// Callback funtion for audio data to be played
     void playerCallback(AudioQueueRef queue, AudioQueueBufferRef bufferRef);
+    /// @return list of available pcm devices
     static std::vector<PcmDevice> pcm_list();
 
 private:
@@ -67,5 +71,3 @@ class CoreAudioPlayer : public Player
 };
 
 } // namespace player
-
-#endif

client/player/file_player.hpp

@@ -16,8 +16,9 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
 ***/
 
-#ifndef FILE_PLAYER_HPP
-#define FILE_PLAYER_HPP
+
+#pragma once
+
 
 // local headers
 #include "player.hpp"
@@ -40,8 +41,10 @@ static constexpr auto FILE = "file";
 class FilePlayer : public Player
 {
 public:
+    /// c'tor
     FilePlayer(boost::asio::io_context& io_context, const ClientSettings::Player& settings, std::shared_ptr<Stream> stream);
-    virtual ~FilePlayer();
+    /// d'tor
+    ~FilePlayer() override;
 
     void start() override;
     void stop() override;
@@ -60,5 +63,3 @@ class FilePlayer : public Player
 };
 
 } // namespace player
-
-#endif

client/player/opensl_player.hpp

@@ -16,8 +16,8 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
 ***/
 
-#ifndef OPEN_SL_PLAYER_HPP
-#define OPEN_SL_PLAYER_HPP
+#pragma once
+
 
 // local headers
 #include "player.hpp"
@@ -35,7 +35,9 @@ namespace player
 
 static constexpr auto OPENSL = "opensl";
 
-typedef int (*AndroidAudioCallback)(short* buffer, int num_samples);
+
+// typedef int (*AndroidAudioCallback)(short* buffer, int num_samples);
+using AndroidAudioCallback = int (*)(short*, int);
 
 
 /// OpenSL Audio Player
@@ -45,12 +47,15 @@ typedef int (*AndroidAudioCallback)(short* buffer, int num_samples);
 class OpenslPlayer : public Player
 {
 public:
+    /// c'tor
     OpenslPlayer(boost::asio::io_context& io_context, const ClientSettings::Player& settings, std::shared_ptr<Stream> stream);
-    virtual ~OpenslPlayer();
+    /// d'tor
+    ~OpenslPlayer() override;
 
     void start() override;
     void stop() override;
 
+    /// Callback to feed data to the player API
     void playerCallback(SLAndroidSimpleBufferQueueItf bq);
 
 private:

client/player/player.hpp

@@ -54,6 +54,7 @@ class Player
         bool mute{false};   ///< muted?
     };
 
+    /// Callback for volume changes on the local client, to notify the server
     using volume_callback = std::function<void(const Volume& volume)>;
 
     /// c'tor
@@ -89,7 +90,6 @@ class Player
 
     /// set the hardware mixer volume
     /// @param volume the volume on range [0..1], muted or not
-    /// @param muted muted or not
     virtual void setHardwareVolume(const Volume& volume);
 
     /// set volume polynomial: volume^exp
@@ -102,7 +102,6 @@ class Player
 
     /// Notify the server about hardware volume changes
     /// @param volume the volume in range [0..1]
-    /// @param muted if muted or not
     void notifyVolumeChange(const Volume& volume) const
     {
         if (onVolumeChanged_)

client/player/wasapi_player.hpp

@@ -16,8 +16,7 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
 ***/
 
-#ifndef WASAPI_PLAYER_HPP
-#define WASAPI_PLAYER_HPP
+#pragma once
 
 #pragma warning(push)
 #pragma warning(disable : 4100)
@@ -206,5 +205,3 @@ class WASAPIPlayer : public Player
 #pragma warning(pop)
 
 } // namespace player
-
-#endif

common/message/json_message.hpp

@@ -54,6 +54,7 @@ class JsonMessage : public BaseMessage
         return static_cast<uint32_t>(sizeof(uint32_t) + msg.dump().size());
     }
 
+    /// the json message payload
     json msg;
 
 

common/message/wire_chunk.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
@@ -39,18 +39,21 @@ namespace msg
 class WireChunk : public BaseMessage
 {
 public:
-    explicit WireChunk(uint32_t size = 0) : BaseMessage(message_type::kWireChunk), payloadSize(size), payload(nullptr)
+    /// c'tor
+    explicit WireChunk(uint32_t size = 0) : BaseMessage(message_type::kWireChunk), payloadSize(size)
     {
         if (size > 0)
             payload = static_cast<char*>(malloc(size * sizeof(char)));
     }
 
+    /// c'tor
     WireChunk(const WireChunk& wireChunk) : BaseMessage(message_type::kWireChunk), timestamp(wireChunk.timestamp), payloadSize(wireChunk.payloadSize)
     {
         payload = static_cast<char*>(malloc(payloadSize));
         memcpy(payload, wireChunk.payload, payloadSize);
     }
 
+    /// d'tor
     ~WireChunk() override
     {
         free(payload);
@@ -73,10 +76,11 @@ class WireChunk : public BaseMessage
         return chronos::time_point_clk(chronos::sec(timestamp.sec) + chronos::usec(timestamp.usec));
     }
 
-    tv timestamp;
-    uint32_t payloadSize;
-    char* payload;
+    tv timestamp;           ///< playout timestamp (server time)
+    uint32_t payloadSize;   ///< size of the payload
+    char* payload{nullptr}; ///< raw chunk payload
 
+    /// @return tuple of payload and payload size
     template <typename T>
     std::pair<T*, size_t> getPayload() const
     {