Add documentation

client/decoder/flac_decoder.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
@@ -32,34 +32,38 @@
 namespace decoder
 {
 
+
+/// Cache internal decoder status
 struct CacheInfo
 {
-    CacheInfo() : sampleRate_(0)
-    {
-        reset();
-    }
-
+    /// Reset current cache info
     void reset()
     {
         isCachedChunk_ = true;
         cachedBlocks_ = 0;
     }
 
-    bool isCachedChunk_;
-    size_t cachedBlocks_;
-    size_t sampleRate_;
+    bool isCachedChunk_{true}; ///< is the current block cached
+    size_t cachedBlocks_{0};   ///< number of cached blocks
+    size_t sampleRate_{0};     ///< sample rate of the block
 };
 
 
+/// Flac decoder
 class FlacDecoder : public Decoder
 {
 public:
+    /// c'tor
     FlacDecoder();
+    /// d'tor
     ~FlacDecoder() override;
+
     bool decode(msg::PcmChunk* chunk) override;
     SampleFormat setHeader(msg::CodecHeader* chunk) override;
 
+    /// Flac internal cache info
     CacheInfo cacheInfo_;
+    /// Last decoder error
     std::unique_ptr<FLAC__StreamDecoderErrorStatus> lastError_;
 
 private:

client/decoder/null_decoder.hpp

@@ -1,6 +1,6 @@
 /***
     This file is part of snapcast
-    Copyright (C) 2014-2023  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
@@ -25,10 +25,13 @@
 namespace decoder
 {
 
+/// Dummy decoder, doing actually nothing
 class NullDecoder : public Decoder
 {
 public:
+    /// c'tor
     NullDecoder();
+
     bool decode(msg::PcmChunk* chunk) override;
     SampleFormat setHeader(msg::CodecHeader* chunk) override;
 };

client/decoder/ogg_decoder.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,11 +36,15 @@
 namespace decoder
 {
 
+/// Ogg decoder
 class OggDecoder : public Decoder
 {
 public:
+    /// c'tor
     OggDecoder();
+    /// d'tor
     ~OggDecoder() override;
+
     bool decode(msg::PcmChunk* chunk) override;
     SampleFormat setHeader(msg::CodecHeader* chunk) override;
 
@@ -57,15 +61,15 @@ class OggDecoder : public Decoder
         return static_cast<T>(value);
     }
 
-    ogg_sync_state oy;   /// sync and verify incoming physical bitstream
-    ogg_stream_state os; /// take physical pages, weld into a logical stream of packets
-    ogg_page og;         /// one Ogg bitstream page. Vorbis packets are inside
-    ogg_packet op;       /// one raw packet of data for decode
+    ogg_sync_state oy;   ///< sync and verify incoming physical bitstream
+    ogg_stream_state os; ///< take physical pages, weld into a logical stream of packets
+    ogg_page og;         ///< one Ogg bitstream page. Vorbis packets are inside
+    ogg_packet op;       ///< one raw packet of data for decode
 
-    vorbis_info vi;      /// struct that stores all the static vorbis bitstream settings
-    vorbis_comment vc;   /// struct that stores all the bitstream user comments
-    vorbis_dsp_state vd; /// central working state for the packet->PCM decoder
-    vorbis_block vb;     /// local working space for packet->PCM decode
+    vorbis_info vi;      ///< struct that stores all the static vorbis bitstream settings
+    vorbis_comment vc;   ///< struct that stores all the bitstream user comments
+    vorbis_dsp_state vd; ///< central working state for the packet->PCM decoder
+    vorbis_block vb;     ///< local working space for packet->PCM decode
 
     SampleFormat sampleFormat_;
     std::mutex mutex_;

client/decoder/opus_decoder.hpp

@@ -1,7 +1,7 @@
 /***
         This file is part of snapcast
         Copyright (C) 2015  Hannes Ellinger
-        Copyright (C) 2016-2024  Johannes Pohl
+        Copyright (C) 2016-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,11 +36,15 @@
 namespace decoder
 {
 
+/// Opus decoder
 class OpusDecoder : public Decoder
 {
 public:
+    /// c'tor
     OpusDecoder();
-    ~OpusDecoder();
+    /// c'tor
+    ~OpusDecoder() override;
+
     bool decode(msg::PcmChunk* chunk) override;
     SampleFormat setHeader(msg::CodecHeader* chunk) override;
 

client/decoder/pcm_decoder.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
@@ -32,24 +32,30 @@ static constexpr auto ID_WAVE = 0x45564157;
 static constexpr auto ID_FMT = 0x20746d66;
 static constexpr auto ID_DATA = 0x61746164;
 
+/// RIFF wave header
+/// See https://en.wikipedia.org/wiki/WAV
 struct riff_wave_header
 {
-    uint32_t riff_id;
-    uint32_t riff_sz;
-    uint32_t wave_id;
+    uint32_t riff_id; ///< "RIFF"
+    uint32_t riff_sz; ///< file size - 8
+    uint32_t wave_id; ///< "WAVE"
 };
 
 
+/// Chunk header
+/// See https://en.wikipedia.org/wiki/WAV
 struct chunk_header
 {
     uint32_t id;
     uint32_t sz;
 };
 
 
+/// Chunk format
+/// See https://en.wikipedia.org/wiki/WAV
 struct chunk_fmt
 {
-    uint16_t audio_format;
+    uint16_t audio_format; ///<
     uint16_t num_channels;
     uint32_t sample_rate;
     uint32_t byte_rate;

client/decoder/pcm_decoder.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
@@ -25,10 +25,13 @@
 namespace decoder
 {
 
+/// PCM decoder
 class PcmDecoder : public Decoder
 {
 public:
+    /// c'tor
     PcmDecoder();
+
     bool decode(msg::PcmChunk* chunk) override;
     SampleFormat setHeader(msg::CodecHeader* chunk) override;
 };

client/player/wasapi_player.cpp

@@ -47,6 +47,7 @@ namespace player
 
 static constexpr auto LOG_TAG = "WASAPI";
 
+/// COMMemDeleter helper
 template <typename T>
 struct COMMemDeleter
 {

client/player/wasapi_player.hpp

@@ -1,6 +1,6 @@
 /***
     This file is part of snapcast
-    Copyright (C) 2014-2022  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
@@ -33,6 +33,7 @@
 namespace player
 {
 
+/// Implementation of IAudioSessionEvents
 class AudioSessionEventListener : public IAudioSessionEvents
 {
     LONG _cRef;
@@ -108,6 +109,7 @@ class AudioSessionEventListener : public IAudioSessionEvents
 };
 
 
+/// Implementation of IAudioEndpointVolumeCallback
 class AudioEndpointVolumeCallback : public IAudioEndpointVolumeCallback
 {
     LONG _cRef;
@@ -178,6 +180,7 @@ class AudioEndpointVolumeCallback : public IAudioEndpointVolumeCallback
 
 static constexpr auto WASAPI = "wasapi";
 
+/// WASAPI player
 class WASAPIPlayer : public Player
 {
 public:

common/snap_exception.hpp

@@ -22,28 +22,33 @@
 #include <exception>
 #include <string>
 
-// text_exception uses a dynamically-allocated internal c-string for what():
+/// Snapcast specific exceptions
 class SnapException : public std::exception
 {
     std::string text_;
     int error_code_;
 
 public:
+    /// c'tor
     explicit SnapException(const char* text, int error_code = 0) : text_(text), error_code_(error_code)
     {
     }
 
+    /// c'tor
     explicit SnapException(const std::string& text, int error_code = 0) : SnapException(text.c_str(), error_code)
     {
     }
 
+    /// d'tor
     ~SnapException() override = default;
 
+    /// @return error code
     int code() const noexcept
     {
         return error_code_;
     }
 
+    /// @return the exception text
     const char* what() const noexcept override
     {
         return text_.c_str();

server/encoder/encoder.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
@@ -45,7 +45,7 @@ class Encoder
 
     /// c'tor
     /// Codec options (E.g. compression level) are passed as string and are codec dependend
-    Encoder(const std::string& codecOptions = "") : headerChunk_(nullptr), codecOptions_(codecOptions)
+    explicit Encoder(std::string codecOptions = "") : headerChunk_(nullptr), codecOptions_(std::move(codecOptions))
     {
     }
 

server/encoder/encoder_factory.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
@@ -40,9 +40,9 @@ using namespace std;
 namespace encoder
 {
 
-std::unique_ptr<Encoder> EncoderFactory::createEncoder(const std::string& codecSettings) const
+std::unique_ptr<Encoder> EncoderFactory::createEncoder(const std::string& codec_settings) const
 {
-    std::string codec(codecSettings);
+    std::string codec(codec_settings);
     std::string codecOptions;
     if (codec.find(':') != std::string::npos)
     {

server/encoder/encoder_factory.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
@@ -29,11 +29,12 @@
 namespace encoder
 {
 
+/// Factory to create an encoder from an URI
 class EncoderFactory
 {
 public:
-    //	EncoderFactory(const std::string& codecSettings);
-    std::unique_ptr<Encoder> createEncoder(const std::string& codecSettings) const;
+    /// @return Encoder from @p codec_settings
+    std::unique_ptr<Encoder> createEncoder(const std::string& codec_settings) const;
 };
 
 } // namespace encoder

server/encoder/flac_encoder.cpp

@@ -40,7 +40,8 @@ namespace encoder
 
 static constexpr auto LOG_TAG = "FlacEnc";
 
-FlacEncoder::FlacEncoder(const std::string& codecOptions) : Encoder(codecOptions), encoder_(nullptr), pcmBufferSize_(0), encodedSamples_(0), flacChunk_(nullptr)
+FlacEncoder::FlacEncoder(std::string codecOptions)
+    : Encoder(std::move(codecOptions)), encoder_(nullptr), pcmBufferSize_(0), encodedSamples_(0), flacChunk_(nullptr)
 {
     headerChunk_ = std::make_shared<msg::CodecHeader>("flac");
     pcmBuffer_ = static_cast<FLAC__int32*>(malloc(pcmBufferSize_ * sizeof(FLAC__int32)));
@@ -230,7 +231,7 @@ void FlacEncoder::initEncoder()
         throw SnapException("out of memory or tag error");
 
     metadata_[1]->length = 1234; // set the padding length
-    ok = FLAC__stream_encoder_set_metadata(encoder_, metadata_, 2);
+    ok = FLAC__stream_encoder_set_metadata(encoder_, metadata_.data(), 2);
     if (ok == 0)
         throw SnapException("error setting meta data");