From 355c75458a254fbd00a32a8ea36fc64ede7f0419 Mon Sep 17 00:00:00 2001
From: badaix <johannes.pohl@badaix.de>
Date: Thu, 23 Jan 2025 22:30:11 +0100
Subject: [PATCH] Add code comments

---
 client/client_settings.hpp   | 43 ++++++++++++++++++++++++++++--------
 client/player/pcm_device.hpp | 15 ++++++++-----
 2 files changed, 44 insertions(+), 14 deletions(-)

diff --git a/client/client_settings.hpp b/client/client_settings.hpp
index 6ebaa20a..5ea4adc0 100644
--- a/client/client_settings.hpp
+++ b/client/client_settings.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
@@ -26,58 +26,83 @@
 #include <string>
 
 
-
+/// Snapclient settings
 struct ClientSettings
 {
+    /// Sharing mode for audio device
     enum class SharingMode
     {
-        unspecified,
-        exclusive,
-        shared
+        unspecified, ///< unspecified
+        exclusive,   ///< exclusice access
+        shared       ///< shared access
     };
 
+    /// Mixer settings
     struct Mixer
     {
+        /// Mixer mode
         enum class Mode
         {
-            hardware,
-            software,
-            script,
-            none
+            hardware, ///< hardware mixer
+            software, ///< software mixer
+            script,   ///< run a mixer script
+            none      ///< no mixer
         };
 
+        /// the configured mixer mode
         Mode mode{Mode::software};
+        /// mixer parameter
         std::string parameter;
     };
 
+    /// Server settings
     struct Server
     {
+        /// server host or IP address
         std::string host;
+        /// protocol: "tcp", "ws" or "wss"
         std::string protocol;
+        /// server port
         size_t port{1704};
     };
 
+    /// The audio player (DAC)
     struct Player
     {
+        /// name of the player
         std::string player_name;
+        /// player parameters
         std::string parameter;
+        /// additional latency of the DAC [ms]
         int latency{0};
+        /// the DAC
         player::PcmDevice pcm_device;
+        /// Sampleformat to be uses, i.e. 48000:16:2
         SampleFormat sample_format;
+        /// The sharing mode
         SharingMode sharing_mode{SharingMode::unspecified};
+        /// Mixer settings
         Mixer mixer;
     };
 
+    /// Log settings
     struct Logging
     {
+        /// The log sink (null,system,stdout,stderr,file:<filename>)
         std::string sink;
+        /// Log filter
         std::string filter{"*:info"};
     };
 
+    /// The snapclient process instance
     size_t instance{1};
+    /// The host id, presented to the server
     std::string host_id;
 
+    /// Server settings
     Server server;
+    /// Player settings
     Player player;
+    /// Logging settings
     Logging logging;
 };
diff --git a/client/player/pcm_device.hpp b/client/player/pcm_device.hpp
index 0cb6af6d..17a03784 100644
--- a/client/player/pcm_device.hpp
+++ b/client/player/pcm_device.hpp
@@ -1,6 +1,6 @@
 /***
     This file is part of snapcast
-    Copyright (C) 2014-2020  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
@@ -16,27 +16,32 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
 ***/
 
-#ifndef PCM_DEVICE_HPP
-#define PCM_DEVICE_HPP
+#pragma once
 
+// standard headers
 #include <string>
 
 namespace player
 {
 
+/// Name of the default audio device
 static constexpr char DEFAULT_DEVICE[] = "default";
 
+/// DAC identifier
 struct PcmDevice
 {
+    /// c'tor
     PcmDevice() : idx(-1), name(DEFAULT_DEVICE){};
 
+    /// c'tor
     PcmDevice(int idx, const std::string& name, const std::string& description = "") : idx(idx), name(name), description(description){};
 
+    /// index of the DAC (as in "aplay -L")
     int idx;
+    /// device name
     std::string name;
+    /// device description
     std::string description;
 };
 
 } // namespace player
-
-#endif