docs(doxygen): enforce warn if undocumented (#5337)

src/audio.cpp

@@ -19,19 +19,35 @@
 
 namespace audio {
   using namespace std::literals;
+  /**
+   * @brief Owning pointer for an Opus multistream encoder.
+   */
   using opus_t = util::safe_ptr<OpusMSEncoder, opus_multistream_encoder_destroy>;
+  /**
+   * @brief Shared queue carrying captured PCM sample buffers to the encoder thread.
+   */
   using sample_queue_t = std::shared_ptr<safe::queue_t<std::vector<float>>>;
 
   static int start_audio_control(audio_ctx_t &ctx);
   static void stop_audio_control(audio_ctx_t &);
   static void apply_surround_params(opus_stream_config_t &stream, const stream_params_t &params);
 
+  /**
+   * @brief Select the Opus stream configuration for a channel count and quality tier.
+   *
+   * @param channels Number of audio channels in the stream.
+   * @param quality Whether the high-quality Opus layout should be selected.
+   * @return Index into `stream_configs` for the requested layout.
+   */
   int map_stream(int channels, bool quality);
 
-  constexpr auto SAMPLE_RATE = 48000;
+  constexpr auto SAMPLE_RATE = 48000;  ///< Audio sample rate in hertz required by Opus.
 
   // NOTE: If you adjust the bitrates listed here, make sure to update the
   // corresponding bitrate adjustment logic in rtsp_stream::cmd_announce()
+  /**
+   * @brief Opus stream layouts and bitrates advertised to clients.
+   */
   opus_stream_config_t stream_configs[MAX_STREAM_CONFIG] {
     {
       SAMPLE_RATE,
@@ -83,6 +99,13 @@ namespace audio {
     },
   };
 
+  /**
+   * @brief Encode captured PCM samples into Opus packets on the audio worker thread.
+   *
+   * @param samples Queue of captured PCM sample buffers to encode.
+   * @param config Audio stream settings negotiated with the client.
+   * @param channel_data Platform-specific audio capture context passed to packet metadata.
+   */
   void encodeThread(sample_queue_t samples, config_t config, void *channel_data) {
     auto packets = mail::man->queue<packet_t>(mail::audio_packets);
     auto stream = stream_configs[map_stream(config.channels, config.flags[config_t::HIGH_QUALITY])];
@@ -128,6 +151,9 @@ namespace audio {
     }
   }
 
+  /**
+   * @brief Run the capture loop for this backend.
+   */
   void capture(safe::mail_t mail, config_t config, void *channel_data) {
     auto shutdown_event = mail->event<bool>(mail::shutdown);
     if (!config::audio.stream) {
@@ -265,6 +291,9 @@ namespace audio {
     return ctx.control->is_sink_available(sink);
   }
 
+  /**
+   * @brief Select the Opus stream configuration for a channel count and quality tier.
+   */
   int map_stream(int channels, bool quality) {
     int shift = quality ? 1 : 0;
     switch (channels) {