From 76f3155f0aa602e96b2547d764ed3f414091cfc5 Mon Sep 17 00:00:00 2001
From: MagnificentJake <63098251+MagnificentJake@users.noreply.github.com>
Date: Thu, 11 Sep 2025 22:44:04 +0100
Subject: [PATCH] Improve documentation of pitch and volume variation in
 AudioStreamRandomizer

Existing documentation did not adequately communicate how the random_pitch and random_volume_offset_db values affected volume and pitch. This change clarifies:
- That the variation is positive or negative.
- What the values actually mean, with examples.

Apply suggestions from code review

Co-authored-by: Hugo Locurcio <hugo.locurcio@hugo.pro>

Update code blocks to skip-lint to pass failed check
---
 doc/classes/AudioStreamRandomizer.xml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/classes/AudioStreamRandomizer.xml b/doc/classes/AudioStreamRandomizer.xml
index 098c1c01598..91b6c4df78a 100644
--- a/doc/classes/AudioStreamRandomizer.xml
+++ b/doc/classes/AudioStreamRandomizer.xml
@@ -69,7 +69,7 @@
 			Controls how this AudioStreamRandomizer picks which AudioStream to play next.
 		</member>
 		<member name="random_pitch" type="float" setter="set_random_pitch" getter="get_random_pitch" default="1.0">
-			The largest possible frequency multiplier of the random pitch variation. A value of [code]1.0[/code] means no variation.
+			The largest possible frequency multiplier of the random pitch variation. Pitch will be randomly chosen within a range of [code skip-lint]1.0 / random_pitch[/code] and [code skip-lint]random_pitch[/code]. A value of [code]1.0[/code] means no variation. A value of [code]2.0[/code] means pitch will be randomized between double and half.
 			[b]Note:[/b] Setting this property also sets [member random_pitch_semitones].
 		</member>
 		<member name="random_pitch_semitones" type="float" setter="set_random_pitch_semitones" getter="get_random_pitch_semitones" default="0.0">
@@ -77,7 +77,7 @@
 			[b]Note:[/b] Setting this property also sets [member random_pitch].
 		</member>
 		<member name="random_volume_offset_db" type="float" setter="set_random_volume_offset_db" getter="get_random_volume_offset_db" default="0.0">
-			The intensity of random volume variation. A value of 0 means no variation.
+			The intensity of random volume variation. Volume will be increased or decreased by a random value up to [code skip-lint]random_volume_offset_db[/code]. A value of [code]0.0[/code] means no variation. A value of [code]3.0[/code] means volume will be randomized between [code]-3.0 dB[/code] and [code]+3.0 dB[/code].
 		</member>
 		<member name="streams_count" type="int" setter="set_streams_count" getter="get_streams_count" default="0">
 			The number of streams in the stream pool.