Overhaul AudioStreamPlayer's documentation

doc/classes/AudioStreamPlayer.xml

@@ -1,11 +1,12 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioStreamPlayer" inherits="Node" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Plays back audio non-positionally.
+		A node for audio playback.
 	</brief_description>
 	<description>
-		Plays an audio stream non-positionally.
-		To play audio positionally, use [AudioStreamPlayer2D] or [AudioStreamPlayer3D] instead of [AudioStreamPlayer].
+		The [AudioStreamPlayer] node plays an audio stream non-positionally. It is ideal for user interfaces, menus, or background music.
+		To use this node, [member stream] needs to be set to a valid [AudioStream] resource. Playing more than one sound at the time is also supported, see [member max_polyphony].
+		If you need to play audio at a specific position, use [AudioStreamPlayer2D] or [AudioStreamPlayer3D] instead.
 	</description>
 	<tutorials>
 		<link title="Audio streams">$DOCS_URL/tutorials/audio/audio_streams.html</link>
@@ -19,82 +20,85 @@
 		<method name="get_playback_position">
 			<return type="float" />
 			<description>
-				Returns the position in the [AudioStream] in seconds.
+				Returns the position in the [AudioStream] of the latest sound, in seconds. Returns [code]0.0[/code] if no sounds are playing.
+				[b]Note:[/b] The position is not always accurate, as the [AudioServer] does not mix audio every processed frame. To get more accurate results, add [method AudioServer.get_time_since_last_mix] to the returned position.
 			</description>
 		</method>
 		<method name="get_stream_playback">
 			<return type="AudioStreamPlayback" />
 			<description>
-				Returns the [AudioStreamPlayback] object associated with this [AudioStreamPlayer].
+				Returns the latest [AudioStreamPlayback] of this node, usually the most recently created by [method play]. If no sounds are playing, this method fails and returns an empty playback.
 			</description>
 		</method>
 		<method name="has_stream_playback">
 			<return type="bool" />
 			<description>
-				Returns whether the [AudioStreamPlayer] can return the [AudioStreamPlayback] object or not.
+				Returns [code]true[/code] if any sound is active, even if [member stream_paused] is set to [code]true[/code]. See also [member playing] and [method get_stream_playback].
 			</description>
 		</method>
 		<method name="play">
 			<return type="void" />
 			<param index="0" name="from_position" type="float" default="0.0" />
 			<description>
-				Plays the audio from the given [param from_position], in seconds.
+				Plays a sound from the beginning, or the given [param from_position] in seconds.
 			</description>
 		</method>
 		<method name="seek">
 			<return type="void" />
 			<param index="0" name="to_position" type="float" />
 			<description>
-				Sets the position from which audio will be played, in seconds.
+				Restarts all sounds to be played from the given [param to_position], in seconds. Does nothing if no sounds are playing.
 			</description>
 		</method>
 		<method name="stop">
 			<return type="void" />
 			<description>
-				Stops the audio.
+				Stops all sounds from this node.
 			</description>
 		</method>
 	</methods>
 	<members>
 		<member name="autoplay" type="bool" setter="set_autoplay" getter="is_autoplay_enabled" default="false">
-			If [code]true[/code], audio plays when added to scene tree.
+			If [code]true[/code], this node calls [method play] when entering the tree.
 		</member>
 		<member name="bus" type="StringName" setter="set_bus" getter="get_bus" default="&amp;&quot;Master&quot;">
-			Bus on which this audio is playing.
-			[b]Note:[/b] When setting this property, keep in mind that no validation is performed to see if the given name matches an existing bus. This is because audio bus layouts might be loaded after this property is set. If this given name can't be resolved at runtime, it will fall back to [code]"Master"[/code].
+			The target bus name. All sounds from this node will be playing on this bus.
+			[b]Note:[/b] At runtime, if no bus with the given name exists, all sounds will fall back on [code]"Master"[/code]. See also [method AudioServer.get_bus_name].
 		</member>
 		<member name="max_polyphony" type="int" setter="set_max_polyphony" getter="get_max_polyphony" default="1">
-			The maximum number of sounds this node can play at the same time. Playing additional sounds after this value is reached will cut off the oldest sounds.
+			The maximum number of sounds this node can play at the same time. Calling [method play] after this value is reached will cut off the oldest sounds.
 		</member>
 		<member name="mix_target" type="int" setter="set_mix_target" getter="get_mix_target" enum="AudioStreamPlayer.MixTarget" default="0">
-			If the audio configuration has more than two speakers, this sets the target channels. See [enum MixTarget] constants.
+			The mix target channels, as one of the [enum MixTarget] constants. Has no effect when two speakers or less are detected (see [enum AudioServer.SpeakerMode]).
 		</member>
 		<member name="pitch_scale" type="float" setter="set_pitch_scale" getter="get_pitch_scale" default="1.0">
-			The pitch and the tempo of the audio, as a multiplier of the audio sample's sample rate.
+			The audio's pitch and tempo, as a multiplier of the [member stream]'s sample rate. A value of [code]2.0[/code] doubles the audio's pitch, while a value of [code]0.5[/code] halves the pitch.
 		</member>
 		<member name="playing" type="bool" setter="_set_playing" getter="is_playing" default="false">
-			If [code]true[/code], audio is playing.
+			If [code]true[/code], this node is playing sounds. Setting this property has the same effect as [method play] and [method stop].
 		</member>
 		<member name="stream" type="AudioStream" setter="set_stream" getter="get_stream">
-			The [AudioStream] object to be played.
+			The [AudioStream] resource to be played. Setting this property stops all currently playing sounds. If left empty, the [AudioStreamPlayer] does not work.
 		</member>
 		<member name="stream_paused" type="bool" setter="set_stream_paused" getter="get_stream_paused" default="false">
-			If [code]true[/code], the playback is paused. You can resume it by setting [member stream_paused] to [code]false[/code].
+			If [code]true[/code], the sounds are paused. Setting [member stream_paused] to [code]false[/code] resumes all sounds.
+			[b]Note:[/b] This property is automatically changed when exiting or entering the tree, or this node is paused (see [member Node.process_mode]).
 		</member>
 		<member name="volume_db" type="float" setter="set_volume_db" getter="get_volume_db" default="0.0">
-			Volume of sound, in dB.
+			Volume of sound, in decibel. This is an offset of the [member stream]'s volume.
+			[b]Note:[/b] To convert between decibel and linear energy (like most volume sliders do), use [method @GlobalScope.db_to_linear] and [method @GlobalScope.linear_to_db].
 		</member>
 	</members>
 	<signals>
 		<signal name="finished">
 			<description>
-				Emitted when the audio stops playing.
+				Emitted when a sound finishes playing without interruptions. This signal is [i]not[/i] emitted when calling [method stop], or when exiting the tree while sounds are playing.
 			</description>
 		</signal>
 	</signals>
 	<constants>
 		<constant name="MIX_TARGET_STEREO" value="0" enum="MixTarget">
-			The audio will be played only on the first channel.
+			The audio will be played only on the first channel. This is the default.
 		</constant>
 		<constant name="MIX_TARGET_SURROUND" value="1" enum="MixTarget">
 			The audio will be played on all surround channels.