Merge pull request #8901 from lioncash/docs

audio_core: Amend documentation comment tags

src/audio_core/audio_core.h

@@ -17,7 +17,7 @@ namespace AudioCore {
 
 class AudioManager;
 /**
- * Main audio class, sotred inside the core, and holding the audio manager, all sinks, and the ADSP.
+ * Main audio class, stored inside the core, and holding the audio manager, all sinks, and the ADSP.
  */
 class AudioCore {
 public:

src/audio_core/audio_event.h

@@ -14,7 +14,7 @@ namespace AudioCore {
  * Responsible for the input/output events, set by the stream backend when buffers are consumed, and
  * waited on by the audio manager. These callbacks signal the game's events to keep the audio buffer
  * recycling going.
- * In a real Switch this is not a seprate class, and exists entirely within the audio manager.
+ * In a real Switch this is not a separate class, and exists entirely within the audio manager.
  * On the Switch it's implemented more simply through a MultiWaitEventHolder, where it can
  * wait on multiple events at once, and the events are not needed by the backend.
  */
@@ -81,7 +81,7 @@ public:
     void ClearEvents();
 
 private:
-    /// Lock, used bythe audio manager
+    /// Lock, used by the audio manager
     std::mutex event_lock;
     /// Array of events, one per system type (see Type), last event is used to terminate
     std::array<std::atomic<bool>, 4> events_signalled;

src/audio_core/audio_in_manager.h

@@ -59,9 +59,10 @@ public:
     /**
      * Get a list of audio in device names.
      *
-     * @oaram names     - Output container to write names to.
+     * @param names     - Output container to write names to.
-     * @param max_count - Maximum numebr of deivce names to write. Unused
+     * @param max_count - Maximum number of device names to write. Unused
      * @param filter    - Should the list be filtered? Unused.
+     *
      * @return Number of names written.
      */
     u32 GetDeviceNames(std::vector<AudioRenderer::AudioDevice::AudioDeviceName>& names,

src/audio_core/audio_manager.h

@@ -76,7 +76,7 @@ public:
 
 private:
     /**
-     * Main thread, waiting on a manager signal and calling the registered fucntion.
+     * Main thread, waiting on a manager signal and calling the registered function.
      */
     void ThreadFunc();
 

src/audio_core/audio_render_manager.h

@@ -64,10 +64,10 @@ public:
 
     /**
      * Add a renderer system to the manager.
-     * The system will be reguarly called to generate commands for the AudioRenderer.
+     * The system will be regularly called to generate commands for the AudioRenderer.
      *
      * @param system - The system to add.
-     * @return True if the system was sucessfully added, otherwise false.
+     * @return True if the system was successfully added, otherwise false.
      */
     bool AddSystem(System& system);
 
@@ -75,7 +75,7 @@ public:
      * Remove a renderer system from the manager.
      *
      * @param system - The system to remove.
-     * @return True if the system was sucessfully removed, otherwise false.
+     * @return True if the system was successfully removed, otherwise false.
      */
     bool RemoveSystem(System& system);
 

src/audio_core/device/audio_buffers.h

@@ -88,7 +88,9 @@ public:
     /**
      * Release all registered buffers.
      *
-     * @param timestamp - The released timestamp for this buffer.
+     * @param core_timing - The CoreTiming instance
+     * @param session     - The device session
+     *
      * @return Is the buffer was released.
      */
     bool ReleaseBuffers(Core::Timing::CoreTiming& core_timing, DeviceSession& session) {

src/audio_core/device/device_session.h

@@ -74,7 +74,8 @@ public:
     /**
      * Check if the buffer for the given tag has been consumed by the backend.
      *
-     * @param tag - Unqiue tag of the buffer to check.
+     * @param buffer - the buffer to check.
+     *
      * @return true if the buffer has been consumed, otherwise false.
      */
     bool IsBufferConsumed(AudioBuffer& buffer) const;

src/audio_core/in/audio_in_system.h

@@ -208,7 +208,7 @@ public:
     /**
      * Set this system's current volume.
      *
-     * @param The new volume.
+     * @param volume The new volume.
      */
     void SetVolume(f32 volume);
 

src/audio_core/out/audio_out_system.h

@@ -199,7 +199,7 @@ public:
     /**
      * Set this system's current volume.
      *
-     * @param The new volume.
+     * @param volume The new volume.
      */
     void SetVolume(f32 volume);
 

src/audio_core/renderer/adsp/adsp.h

@@ -63,8 +63,6 @@ public:
 
     /**
      * Stop the ADSP.
-     *
-     * @return True if started or already running, otherwise false.
      */
     void Stop();
 

src/audio_core/renderer/adsp/audio_renderer.h

@@ -52,7 +52,7 @@ public:
     /**
      * Send a message from the host to the AudioRenderer.
      *
-     * @param message_ - The message to send to the AudioRenderer.
+     * @param message - The message to send to the AudioRenderer.
      */
     void HostSendMessage(RenderMessage message);
 
@@ -66,7 +66,7 @@ public:
     /**
      * Send a message from the AudioRenderer to the host.
      *
-     * @param message_ - The message to send to the host.
+     * @param message - The message to send to the host.
      */
     void ADSPSendMessage(RenderMessage message);
 
@@ -163,7 +163,7 @@ public:
     /**
      * Start the AudioRenderer.
      *
-     * @param The mailbox to use for this session.
+     * @param mailbox The mailbox to use for this session.
      */
     void Start(AudioRenderer_Mailbox* mailbox);
 

src/audio_core/renderer/adsp/command_list_processor.h

@@ -33,10 +33,10 @@ public:
     /**
      * Initialize the processor.
      *
-     * @param system_ - The core system.
+     * @param system - The core system.
      * @param buffer - The command buffer to process.
      * @param size   - The size of the buffer.
-     * @param stream_ - The stream to be used for sending the samples.
+     * @param stream - The stream to be used for sending the samples.
      */
     void Initialize(Core::System& system, CpuAddr buffer, u64 size, Sink::SinkStream* stream);
 
@@ -72,7 +72,8 @@ public:
     /**
      * Process the command list.
      *
-     * @param index - Index of the current command list.
+     * @param session_id - Session ID for the commands being processed.
+     *
      * @return The time taken to process.
      */
     u64 Process(u32 session_id);
@@ -89,7 +90,7 @@ public:
     u8* commands{};
     /// The command buffer size
     u64 commands_buffer_size{};
-    /// The maximum processing time alloted
+    /// The maximum processing time allotted
     u64 max_process_time{};
     /// The number of commands in the buffer
     u32 command_count{};

src/audio_core/renderer/command/command_buffer.h

@@ -191,6 +191,7 @@ public:
      * @param volume       - Current mix volume used for calculating the ramp.
      * @param prev_volume  - Previous mix volume, used for calculating the ramp,
      *                       also applied to the input.
+     * @param prev_samples - Previous sample buffer. Used for depopping.
      * @param precision    - Number of decimal bits for fixed point operations.
      */
     void GenerateMixRampCommand(s32 node_id, s16 buffer_count, s16 input_index, s16 output_index,
@@ -208,6 +209,7 @@ public:
      * @param volumes      - Current mix volumes used for calculating the ramp.
      * @param prev_volumes - Previous mix volumes, used for calculating the ramp,
      *                       also applied to the input.
+     * @param prev_samples - Previous sample buffer. Used for depopping.
      * @param precision    - Number of decimal bits for fixed point operations.
      */
     void GenerateMixRampGroupedCommand(s32 node_id, s16 buffer_count, s16 input_index,
@@ -300,8 +302,8 @@ public:
      * @param node_id        - Node id of the voice this command is generated for.
      * @param buffer_offset  - Base mix buffer offset to use.
      * @param sink_info      - The sink_info to generate this command from.
-     * @session_id          - System session id this command is generated from.
+     * @param session_id     - System session id this command is generated from.
-     * @samples_buffer      - The buffer to be sent to the sink if upsampling is not used.
+     * @param samples_buffer - The buffer to be sent to the sink if upsampling is not used.
      */
     void GenerateDeviceSinkCommand(s32 node_id, s16 buffer_offset, SinkInfoBase& sink_info,
                                    u32 session_id, std::span<s32> samples_buffer);

src/audio_core/renderer/command/command_generator.h

@@ -198,7 +198,7 @@ public:
      * Generate an I3DL2 reverb effect command.
      *
      * @param buffer_offset - Base mix buffer offset to use.
-     * @param effect_info_base - I3DL2Reverb effect info.
+     * @param effect_info   - I3DL2Reverb effect info.
      * @param node_id       - Node id of the mix this command is generated for.
      */
     void GenerateI3dl2ReverbEffectCommand(s16 buffer_offset, EffectInfoBase& effect_info,
@@ -208,7 +208,7 @@ public:
      * Generate an aux effect command.
      *
      * @param buffer_offset - Base mix buffer offset to use.
-     * @param effect_info_base - Aux effect info.
+     * @param effect_info   - Aux effect info.
      * @param node_id       - Node id of the mix this command is generated for.
      */
     void GenerateAuxCommand(s16 buffer_offset, EffectInfoBase& effect_info, s32 node_id);
@@ -217,7 +217,7 @@ public:
      * Generate a biquad filter effect command.
      *
      * @param buffer_offset - Base mix buffer offset to use.
-     * @param effect_info_base - Aux effect info.
+     * @param effect_info   - Aux effect info.
      * @param node_id       - Node id of the mix this command is generated for.
      */
     void GenerateBiquadFilterEffectCommand(s16 buffer_offset, EffectInfoBase& effect_info,
@@ -227,7 +227,7 @@ public:
      * Generate a light limiter effect command.
      *
      * @param buffer_offset - Base mix buffer offset to use.
-     * @param effect_info_base - Limiter effect info.
+     * @param effect_info   - Limiter effect info.
      * @param node_id       - Node id of the mix this command is generated for.
      * @param effect_index  - Index for the statistics state.
      */
@@ -239,7 +239,7 @@ public:
      * Writes a mix buffer back to game memory.
      *
      * @param buffer_offset - Base mix buffer offset to use.
-     * @param effect_info_base - Capture effect info.
+     * @param effect_info   - Capture effect info.
      * @param node_id       - Node id of the mix this command is generated for.
      */
     void GenerateCaptureCommand(s16 buffer_offset, EffectInfoBase& effect_info, s32 node_id);
@@ -248,11 +248,10 @@ public:
      * Generate a compressor effect command.
      *
      * @param buffer_offset - Base mix buffer offset to use.
-     * @param effect_info_base - Compressor effect info.
+     * @param effect_info   - Compressor effect info.
      * @param node_id       - Node id of the mix this command is generated for.
      */
-    void GenerateCompressorCommand(const s16 buffer_offset, EffectInfoBase& effect_info,
+    void GenerateCompressorCommand(s16 buffer_offset, EffectInfoBase& effect_info, s32 node_id);
-                                   const s32 node_id);
 
     /**
      * Generate all effect commands for a mix.
@@ -318,8 +317,9 @@ public:
      * Generate a performance command.
      * Used to report performance metrics of the AudioRenderer back to the game.
      *
-     * @param buffer_offset - Base mix buffer offset to use.
+     * @param node_id         - Node ID of the mix this command is generated for
-     * @param sink_info     - Sink info to generate the commands from.
+     * @param state           - Output state of the generated performance command
+     * @param entry_addresses - Addresses to be written
      */
     void GeneratePerformanceCommand(s32 node_id, PerformanceState state,
                                     const PerformanceEntryAddresses& entry_addresses);

src/audio_core/renderer/command/mix/mix_ramp.cpp

@@ -7,17 +7,7 @@
 #include "common/logging/log.h"
 
 namespace AudioCore::AudioRenderer {
-/**
+
- * Mix input mix buffer into output mix buffer, with volume applied to the input.
- *
- * @tparam Q           - Number of bits for fixed point operations.
- * @param output       - Output mix buffer.
- * @param input        - Input mix buffer.
- * @param volume       - Volume applied to the input.
- * @param ramp         - Ramp applied to volume every sample.
- * @param sample_count - Number of samples to process.
- * @return The final gained input sample, used for depopping.
- */
 template <size_t Q>
 s32 ApplyMixRamp(std::span<s32> output, std::span<const s32> input, const f32 volume_,
                  const f32 ramp_, const u32 sample_count) {
@@ -40,10 +30,8 @@ s32 ApplyMixRamp(std::span<s32> output, std::span<const s32> input, const f32 vo
     return sample.to_int();
 }
 
-template s32 ApplyMixRamp<15>(std::span<s32>, std::span<const s32>, const f32, const f32,
+template s32 ApplyMixRamp<15>(std::span<s32>, std::span<const s32>, f32, f32, u32);
-                              const u32);
+template s32 ApplyMixRamp<23>(std::span<s32>, std::span<const s32>, f32, f32, u32);
-template s32 ApplyMixRamp<23>(std::span<s32>, std::span<const s32>, const f32, const f32,
-                              const u32);
 
 void MixRampCommand::Dump(const ADSP::CommandListProcessor& processor, std::string& string) {
     const auto ramp{(volume - prev_volume) / static_cast<f32>(processor.sample_count)};

src/audio_core/renderer/command/mix/mix_ramp.h

@@ -61,13 +61,13 @@ struct MixRampCommand : ICommand {
  * @tparam Q           - Number of bits for fixed point operations.
  * @param output       - Output mix buffer.
  * @param input        - Input mix buffer.
- * @param volume       - Volume applied to the input.
+ * @param volume_      - Volume applied to the input.
- * @param ramp         - Ramp applied to volume every sample.
+ * @param ramp_        - Ramp applied to volume every sample.
  * @param sample_count - Number of samples to process.
  * @return The final gained input sample, used for depopping.
  */
 template <size_t Q>
-s32 ApplyMixRamp(std::span<s32> output, std::span<const s32> input, const f32 volume_,
+s32 ApplyMixRamp(std::span<s32> output, std::span<const s32> input, f32 volume_, f32 ramp_,
-                 const f32 ramp_, const u32 sample_count);
+                 u32 sample_count);
 
 } // namespace AudioCore::AudioRenderer

src/audio_core/renderer/command/mix/mix_ramp_grouped.h

@@ -50,9 +50,9 @@ struct MixRampGroupedCommand : ICommand {
     std::array<s16, MaxMixBuffers> inputs;
     /// Output mix buffer indexes for each mix buffer
     std::array<s16, MaxMixBuffers> outputs;
-    /// Previous mix vloumes for each mix buffer
+    /// Previous mix volumes for each mix buffer
     std::array<f32, MaxMixBuffers> prev_volumes;
-    /// Current mix vloumes for each mix buffer
+    /// Current mix volumes for each mix buffer
     std::array<f32, MaxMixBuffers> volumes;
     /// Pointer to the previous sample buffer, used for depop
     CpuAddr previous_samples;

src/audio_core/renderer/effect/effect_context.h

@@ -15,15 +15,15 @@ class EffectContext {
 public:
     /**
      * Initialize the effect context
-     * @param effect_infos List of effect infos for this context
+     * @param effect_infos_      - List of effect infos for this context
-     * @param effect_count The number of effects in the list
+     * @param effect_count_      - The number of effects in the list
-     * @param result_states_cpu The workbuffer of result states for the CPU for this context
+     * @param result_states_cpu_ - The workbuffer of result states for the CPU for this context
-     * @param result_states_dsp The workbuffer of result states for the DSP for this context
+     * @param result_states_dsp_ - The workbuffer of result states for the DSP for this context
-     * @param state_count The number of result states
+     * @param dsp_state_count    - The number of result states
      */
-    void Initialize(std::span<EffectInfoBase> effect_infos_, const u32 effect_count_,
+    void Initialize(std::span<EffectInfoBase> effect_infos_, u32 effect_count_,
                     std::span<EffectResultState> result_states_cpu_,
-                    std::span<EffectResultState> result_states_dsp_, const size_t dsp_state_count);
+                    std::span<EffectResultState> result_states_dsp_, size_t dsp_state_count);
 
     /**
      * Get the EffectInfo for a given index

src/audio_core/renderer/effect/effect_info_base.h

@@ -291,7 +291,7 @@ public:
      * Update the info with new parameters, version 1.
      *
      * @param error_info  - Used to write call result code.
-     * @param in_params   - New parameters to update the info with.
+     * @param params      - New parameters to update the info with.
      * @param pool_mapper - Pool for mapping buffers.
      */
     virtual void Update(BehaviorInfo::ErrorInfo& error_info,
@@ -305,7 +305,7 @@ public:
      * Update the info with new parameters, version 2.
      *
      * @param error_info  - Used to write call result code.
-     * @param in_params   - New parameters to update the info with.
+     * @param params      - New parameters to update the info with.
      * @param pool_mapper - Pool for mapping buffers.
      */
     virtual void Update(BehaviorInfo::ErrorInfo& error_info,

src/audio_core/renderer/memory/address_info.h

@@ -19,8 +19,8 @@ public:
     /**
      * Setup a new AddressInfo.
      *
-     * @param cpu_address - The CPU address of this region.
+     * @param cpu_address_ - The CPU address of this region.
-     * @param size        - The size of this region.
+     * @param size_        - The size of this region.
      */
     void Setup(CpuAddr cpu_address_, u64 size_) {
         cpu_address = cpu_address_;
@@ -42,7 +42,6 @@ public:
      * Assign this region to a memory pool.
      *
      * @param memory_pool_ - Memory pool to assign.
-     * @return The CpuAddr address of this region.
      */
     void SetPool(MemoryPoolInfo* memory_pool_) {
         memory_pool = memory_pool_;

src/audio_core/renderer/nodes/node_states.h

@@ -112,11 +112,11 @@ public:
     /**
      * Initialize the node states.
      *
-     * @param buffer           - The workbuffer to use. Unused.
+     * @param buffer_          - The workbuffer to use. Unused.
      * @param node_buffer_size - The size of the workbuffer. Unused.
      * @param count            - The number of nodes in the graph.
      */
-    void Initialize(std::span<u8> nodes, u64 node_buffer_size, u32 count);
+    void Initialize(std::span<u8> buffer_, u64 node_buffer_size, u32 count);
 
     /**
      * Sort the graph. Only calls DepthFirstSearch.

src/audio_core/renderer/performance/performance_manager.h

@@ -74,6 +74,7 @@ public:
      *
      * @param behavior - Check which version is supported.
      * @param params   - Input parameters.
+     *
      * @return Required workbuffer size.
      */
     static u64 GetRequiredBufferSizeForPerformanceMetricsPerFrame(
@@ -161,6 +162,7 @@ public:
      *
      * @param addresses       - Filled with pointers to the new detail, which should be passed
      *                          to the AudioRenderer with Performance commands to be written.
+     * @param detail_type     - Performance detail type.
      * @param entry_type      - The type of this detail. See PerformanceEntryType
      * @param node_id         - Node id for this detail.
      * @return True if a new detail was created and the offsets are valid, otherwise false.

src/audio_core/renderer/upsampler/upsampler_manager.h

@@ -27,7 +27,7 @@ public:
     /**
      * Free the given upsampler.
      *
-     * @param The upsampler to be freed.
+     * @param info The upsampler to be freed.
      */
     void Free(UpsamplerInfo* info);
 

src/audio_core/renderer/voice/voice_info.h

@@ -185,7 +185,8 @@ public:
     /**
      * Does this voice ned an update?
      *
-     * @param params - Input parametetrs to check matching.
+     * @param params - Input parameters to check matching.
+     *
      * @return True if this voice needs an update, otherwise false.
      */
     bool ShouldUpdateParameters(const InParameter& params) const;
@@ -194,7 +195,7 @@ public:
      * Update the parameters of this voice.
      *
      * @param error_info  - Output error code.
-     * @param params      - Input parametters to udpate from.
+     * @param params      - Input parameters to update from.
      * @param pool_mapper - Used to map buffers.
      * @param behavior    - behavior to check supported features.
      */
@@ -220,7 +221,7 @@ public:
      *
      * @param error_infos  - Output 2D array of errors, 2 per wavebuffer.
      * @param error_count  - Number of errors provided. Unused.
-     * @param params - Input parametters to be used for the update.
+     * @param params       - Input parameters to be used for the update.
      * @param voice_states - The voice states for each channel in this voice to be updated.
      * @param pool_mapper  - Used to map the wavebuffers.
      * @param behavior     - Used to check for supported features.
@@ -233,7 +234,7 @@ public:
     /**
      * Update a wavebuffer.
      *
-     * @param error_infos          - Output array of errors.
+     * @param error_info           - Output array of errors.
      * @param wave_buffer          - The wavebuffer to be updated.
      * @param wave_buffer_internal - Input parametters to be used for the update.
      * @param sample_format        - Sample format of the wavebuffer.
@@ -276,7 +277,7 @@ public:
     /**
      * Check if this voice has any mixing connections.
      *
-     * @return True if this voice participes in mixing, otherwise false.
+     * @return True if this voice participates in mixing, otherwise false.
      */
     bool HasAnyConnection() const;
 
@@ -301,7 +302,8 @@ public:
     /**
      * Update this voice on command generation.
      *
-     * @param voice_states  - Voice states for these wavebuffers.
+     * @param voice_context - Voice context for these wavebuffers.
+     *
      * @return True if this voice should be generated, otherwise false.
      */
     bool UpdateForCommandGeneration(VoiceContext& voice_context);

src/audio_core/sink/cubeb_sink.h

@@ -34,8 +34,7 @@ public:
      *                          May differ from the device's channel count.
      * @param name            - Name of this stream.
      * @param type            - Type of this stream, render/in/out.
-     * @param event           - Audio render only, a signal used to prevent the renderer running too
+     *
-     *                          fast.
      * @return A pointer to the created SinkStream
      */
     SinkStream* AcquireSinkStream(Core::System& system, u32 system_channels,
@@ -101,7 +100,7 @@ private:
 };
 
 /**
- * Get a list of conencted devices from Cubeb.
+ * Get a list of connected devices from Cubeb.
  *
  * @param capture - Return input (capture) devices if true, otherwise output devices.
  */

src/audio_core/sink/sdl2_sink.h

@@ -32,8 +32,7 @@ public:
      *                          May differ from the device's channel count.
      * @param name            - Name of this stream.
      * @param type            - Type of this stream, render/in/out.
-     * @param event           - Audio render only, a signal used to prevent the renderer running too
+     *
-     *                          fast.
      * @return A pointer to the created SinkStream
      */
     SinkStream* AcquireSinkStream(Core::System& system, u32 system_channels,
@@ -92,7 +91,7 @@ private:
 };
 
 /**
- * Get a list of conencted devices from Cubeb.
+ * Get a list of connected devices from SDL.
  *
  * @param capture - Return input (capture) devices if true, otherwise output devices.
  */

src/audio_core/sink/sink.h

@@ -58,8 +58,7 @@ public:
      *                          May differ from the device's channel count.
      * @param name            - Name of this stream.
      * @param type            - Type of this stream, render/in/out.
-     * @param event           - Audio render only, a signal used to prevent the renderer running too
+     *
-     *                          fast.
      * @return A pointer to the created SinkStream
      */
     virtual SinkStream* AcquireSinkStream(Core::System& system, u32 system_channels,

src/audio_core/sink/sink_stream.h

@@ -214,7 +214,7 @@ protected:
     Core::System& system;
     /// Type of this stream
     StreamType type;
-    /// Set by the audio render/in/out systen which uses this stream
+    /// Set by the audio render/in/out system which uses this stream
     u32 system_channels{2};
     /// Channels supported by hardware
     u32 device_channels{2};