Merge pull request #86958 from Mickeon/reduz-adds-stuff,-refuses-to-elaborate,-leaves

Add missing documentation for AudioStream & AudioStreamPlayback

doc/classes/AudioServer.xml

@@ -281,6 +281,8 @@
 			<return type="void" />
 			<param index="0" name="enable" type="bool" />
 			<description>
+				If set to [code]true[/code], all instances of [AudioStreamPlayback] will call [method AudioStreamPlayback._tag_used_streams] every mix step.
+				[b]Note:[/b] This is enabled by default in the editor, as it is used by editor plugins for the audio stream previews.
 			</description>
 		</method>
 		<method name="swap_bus_effects">

doc/classes/AudioStream.xml

@@ -16,16 +16,21 @@
 		<method name="_get_beat_count" qualifiers="virtual const">
 			<return type="int" />
 			<description>
+				Overridable method. Should return the total number of beats of this audio stream. Used by the engine to determine the position of every beat.
+				Ideally, the returned value should be based off the stream's sample rate ([member AudioStreamWAV.mix_rate], for example).
 			</description>
 		</method>
 		<method name="_get_bpm" qualifiers="virtual const">
 			<return type="float" />
 			<description>
+				Overridable method. Should return the tempo of this audio stream, in beats per minute (BPM). Used by the engine to determine the position of every beat.
+				Ideally, the returned value should be based off the stream's sample rate ([member AudioStreamWAV.mix_rate], for example).
 			</description>
 		</method>
 		<method name="_get_length" qualifiers="virtual const">
 			<return type="float" />
 			<description>
+				Override this method to customize the returned value of [method get_length]. Should return the length of this audio stream, in seconds.
 			</description>
 		</method>
 		<method name="_get_parameter_list" qualifiers="virtual const">
@@ -37,16 +42,19 @@
 		<method name="_get_stream_name" qualifiers="virtual const">
 			<return type="String" />
 			<description>
+				Override this method to customize the name assigned to this audio stream. Unused by the engine.
 			</description>
 		</method>
 		<method name="_instantiate_playback" qualifiers="virtual const">
 			<return type="AudioStreamPlayback" />
 			<description>
+				Override this method to customize the returned value of [method instantiate_playback]. Should returned a new [AudioStreamPlayback] created when the stream is played (such as by an [AudioStreamPlayer])..
 			</description>
 		</method>
 		<method name="_is_monophonic" qualifiers="virtual const">
 			<return type="bool" />
 			<description>
+				Override this method to customize the returned value of [method is_monophonic]. Should return [code]true[/code] if this audio stream only supports one channel.
 			</description>
 		</method>
 		<method name="get_length" qualifiers="const">
@@ -58,13 +66,13 @@
 		<method name="instantiate_playback">
 			<return type="AudioStreamPlayback" />
 			<description>
-				Returns an AudioStreamPlayback. Useful for when you want to extend [method _instantiate_playback] but call [method instantiate_playback] from an internally held AudioStream subresource. An example of this can be found in the source files for [code]AudioStreamRandomPitch::instantiate_playback[/code].
+				Returns a newly created [AudioStreamPlayback] intended to play this audio stream. Useful for when you want to extend [method _instantiate_playback] but call [method instantiate_playback] from an internally held AudioStream subresource. An example of this can be found in the source code for [code]AudioStreamRandomPitch::instantiate_playback[/code].
 			</description>
 		</method>
 		<method name="is_monophonic" qualifiers="const">
 			<return type="bool" />
 			<description>
-				Returns true if this audio stream only supports monophonic playback, or false if the audio stream supports polyphony.
+				Returns [code]true[/code] if this audio stream only supports one channel ([i]monophony[/i]), or [code]false[/code] if the audio stream supports two or more channels ([i]polyphony[/i]).
 			</description>
 		</method>
 	</methods>

doc/classes/AudioStreamPlayback.xml

@@ -13,6 +13,7 @@
 		<method name="_get_loop_count" qualifiers="virtual const">
 			<return type="int" />
 			<description>
+				Overridable method. Should return how many times this audio stream has looped. Most built-in playbacks always return [code]0[/code].
 			</description>
 		</method>
 		<method name="_get_parameter" qualifiers="virtual const">
@@ -25,11 +26,13 @@
 		<method name="_get_playback_position" qualifiers="virtual const">
 			<return type="float" />
 			<description>
+				Overridable method. Should return the current progress along the audio stream, in seconds.
 			</description>
 		</method>
 		<method name="_is_playing" qualifiers="virtual const">
 			<return type="bool" />
 			<description>
+				Overridable method. Should return [code]true[/code] if this playback is active and playing its audio stream.
 			</description>
 		</method>
 		<method name="_mix" qualifiers="virtual">
@@ -38,12 +41,15 @@
 			<param index="1" name="rate_scale" type="float" />
 			<param index="2" name="frames" type="int" />
 			<description>
+				Override this method to customize how the audio stream is mixed. This method is called even if the playback is not active.
+				[b]Note:[/b] It is not useful to override this method in GDScript or C#. Only GDExtension can take advantage of it.
 			</description>
 		</method>
 		<method name="_seek" qualifiers="virtual">
 			<return type="void" />
 			<param index="0" name="position" type="float" />
 			<description>
+				Override this method to customize what happens when seeking this audio stream at the given [param position], such as by calling [method AudioStreamPlayer.seek].
 			</description>
 		</method>
 		<method name="_set_parameter" qualifiers="virtual">
@@ -58,16 +64,19 @@
 			<return type="void" />
 			<param index="0" name="from_pos" type="float" />
 			<description>
+				Override this method to customize what happens when the playback starts at the given position, such as by calling [method AudioStreamPlayer.play].
 			</description>
 		</method>
 		<method name="_stop" qualifiers="virtual">
 			<return type="void" />
 			<description>
+				Override this method to customize what happens when the playback is stopped, such as by calling [method AudioStreamPlayer.stop].
 			</description>
 		</method>
 		<method name="_tag_used_streams" qualifiers="virtual">
 			<return type="void" />
 			<description>
+				Overridable method. Called whenever the audio stream is mixed if the playback is active and [method AudioServer.set_enable_tagging_used_audio_streams] has been set to [code]true[/code]. Editor plugins may use this method to "tag" the current position along the audio stream and display it in a preview.
 			</description>
 		</method>
 	</methods>