From 3ac7cc9e574901027f54d97550ddf0ef848a15a3 Mon Sep 17 00:00:00 2001
From: Grosskopf <gerrit@familiegrosskopf.de>
Date: Tue, 10 Oct 2017 16:00:10 +0200
Subject: [PATCH] updated AudioStream docs and added AudioServer docs

---
 doc/classes/AudioBusLayout.xml      |  2 ++
 doc/classes/AudioServer.xml         | 37 +++++++++++++++++++++++++++++
 doc/classes/AudioStreamPlayback.xml |  2 ++
 doc/classes/AudioStreamPlayer.xml   | 10 ++++++--
 doc/classes/AudioStreamPlayer2D.xml |  5 ++--
 doc/classes/AudioStreamPlayer3D.xml |  5 ++--
 6 files changed, 55 insertions(+), 6 deletions(-)

diff --git a/doc/classes/AudioBusLayout.xml b/doc/classes/AudioBusLayout.xml
index e5b17b8dfb7..045c6c2bf96 100644
--- a/doc/classes/AudioBusLayout.xml
+++ b/doc/classes/AudioBusLayout.xml
@@ -1,8 +1,10 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioBusLayout" inherits="Resource" category="Core" version="3.0.alpha.custom_build">
 	<brief_description>
+		Stores information about the audiobusses.
 	</brief_description>
 	<description>
+		Stores position, muting, solo, bypass, effects, effect position, volume, and the connections between busses. See [AudioServer] for usage.
 	</description>
 	<tutorials>
 	</tutorials>
diff --git a/doc/classes/AudioServer.xml b/doc/classes/AudioServer.xml
index 768987fd0b1..0a59da5355b 100644
--- a/doc/classes/AudioServer.xml
+++ b/doc/classes/AudioServer.xml
@@ -17,6 +17,7 @@
 			<argument index="0" name="at_position" type="int" default="-1">
 			</argument>
 			<description>
+				Adds a bus at [code]at_position[/code].
 			</description>
 		</method>
 		<method name="add_bus_effect">
@@ -29,18 +30,21 @@
 			<argument index="2" name="at_position" type="int" default="-1">
 			</argument>
 			<description>
+				Adds an [AudioEffect] effect to the bus [code]bus_idx[/code] at [code]at_position[/code].
 			</description>
 		</method>
 		<method name="generate_bus_layout" qualifiers="const">
 			<return type="AudioBusLayout">
 			</return>
 			<description>
+				Generates an [AudioBusLayout] using the available busses and effects.
 			</description>
 		</method>
 		<method name="get_bus_count" qualifiers="const">
 			<return type="int">
 			</return>
 			<description>
+				Returns the number of available busses.
 			</description>
 		</method>
 		<method name="get_bus_effect">
@@ -51,6 +55,7 @@
 			<argument index="1" name="effect_idx" type="int">
 			</argument>
 			<description>
+				Returns the [AudioEffect] at position [code]effect_idx[/code] in bus [code]bus_idx[/code].
 			</description>
 		</method>
 		<method name="get_bus_effect_count">
@@ -59,6 +64,7 @@
 			<argument index="0" name="bus_idx" type="int">
 			</argument>
 			<description>
+				Returns the number of effects on the bus at [code]bus_idx[/code].
 			</description>
 		</method>
 		<method name="get_bus_index" qualifiers="const">
@@ -67,6 +73,7 @@
 			<argument index="0" name="bus_name" type="String">
 			</argument>
 			<description>
+				Returns the index of the bus with the name [code]bus_name[/code].
 			</description>
 		</method>
 		<method name="get_bus_name" qualifiers="const">
@@ -75,6 +82,7 @@
 			<argument index="0" name="bus_idx" type="int">
 			</argument>
 			<description>
+				Returns the name of the bus with the index [code]bus_idx[/code].
 			</description>
 		</method>
 		<method name="get_bus_peak_volume_left_db" qualifiers="const">
@@ -85,6 +93,7 @@
 			<argument index="1" name="channel" type="int">
 			</argument>
 			<description>
+				Returns the peak volume of the left speaker at bus index [code]bus_idx[/code] and channel index [code]channel[/code].
 			</description>
 		</method>
 		<method name="get_bus_peak_volume_right_db" qualifiers="const">
@@ -95,6 +104,7 @@
 			<argument index="1" name="channel" type="int">
 			</argument>
 			<description>
+				Returns the peak volume of the right speaker at bus index [code]bus_idx[/code] and channel index [code]channel[/code].
 			</description>
 		</method>
 		<method name="get_bus_send" qualifiers="const">
@@ -103,6 +113,7 @@
 			<argument index="0" name="bus_idx" type="int">
 			</argument>
 			<description>
+				Returns the name of the bus that the bus at index [code]bus_idx[/code] sends to.
 			</description>
 		</method>
 		<method name="get_bus_volume_db" qualifiers="const">
@@ -111,18 +122,21 @@
 			<argument index="0" name="bus_idx" type="int">
 			</argument>
 			<description>
+				Returns the volume of the bus at index [code]bus_idx[/code] in dB.
 			</description>
 		</method>
 		<method name="get_mix_rate" qualifiers="const">
 			<return type="float">
 			</return>
 			<description>
+				Returns the sample rate at the output of the audioserver.
 			</description>
 		</method>
 		<method name="get_speaker_mode" qualifiers="const">
 			<return type="int" enum="AudioServer.SpeakerMode">
 			</return>
 			<description>
+				Returns the speaker configuration.
 			</description>
 		</method>
 		<method name="is_bus_bypassing_effects" qualifiers="const">
@@ -131,6 +145,7 @@
 			<argument index="0" name="bus_idx" type="int">
 			</argument>
 			<description>
+				If [code]true[/code] the bus at index [code]bus_idx[/code] is bypassing effects.
 			</description>
 		</method>
 		<method name="is_bus_effect_enabled" qualifiers="const">
@@ -141,6 +156,7 @@
 			<argument index="1" name="effect_idx" type="int">
 			</argument>
 			<description>
+				If [code]true[/code] the effect at index [code]effect_idx[/code] on the bus at index [code]bus_idx[/code] is enabled.
 			</description>
 		</method>
 		<method name="is_bus_mute" qualifiers="const">
@@ -149,6 +165,7 @@
 			<argument index="0" name="bus_idx" type="int">
 			</argument>
 			<description>
+				If [code]true[/code] the bus at index [code]bus_idx[/code] is muted.
 			</description>
 		</method>
 		<method name="is_bus_solo" qualifiers="const">
@@ -157,12 +174,14 @@
 			<argument index="0" name="bus_idx" type="int">
 			</argument>
 			<description>
+				If [code]true[/code] the bus at index [code]bus_idx[/code] is in solo mode.
 			</description>
 		</method>
 		<method name="lock">
 			<return type="void">
 			</return>
 			<description>
+				Locks the audio drivers mainloop. Remember to unlock it afterwards.
 			</description>
 		</method>
 		<method name="move_bus">
@@ -173,6 +192,7 @@
 			<argument index="1" name="to_index" type="int">
 			</argument>
 			<description>
+				Moves the bus from index [code]index[/code] to index [code]to_index[/code].
 			</description>
 		</method>
 		<method name="remove_bus">
@@ -181,6 +201,7 @@
 			<argument index="0" name="index" type="int">
 			</argument>
 			<description>
+				Removes the bus at index [code]index[/code].
 			</description>
 		</method>
 		<method name="remove_bus_effect">
@@ -191,6 +212,7 @@
 			<argument index="1" name="effect_idx" type="int">
 			</argument>
 			<description>
+				Removes the effect at index [code]effect_idx[/code] from the bus at index [code]bus_idx[/code].
 			</description>
 		</method>
 		<method name="set_bus_bypass_effects">
@@ -201,6 +223,7 @@
 			<argument index="1" name="enable" type="bool">
 			</argument>
 			<description>
+				If [code]true[/code] the bus at index [code]bus_idx[/code] is bypassing effects.
 			</description>
 		</method>
 		<method name="set_bus_count">
@@ -209,6 +232,7 @@
 			<argument index="0" name="amount" type="int">
 			</argument>
 			<description>
+				Adds and removes busses to make the number of busses match [code]amount[/code].
 			</description>
 		</method>
 		<method name="set_bus_effect_enabled">
@@ -221,6 +245,7 @@
 			<argument index="2" name="enabled" type="bool">
 			</argument>
 			<description>
+				If [code]true[/code] the effect at index [code]effect_idx[/code] on the bus at index [code]bus_idx[/code] is enabled.
 			</description>
 		</method>
 		<method name="set_bus_layout">
@@ -229,6 +254,7 @@
 			<argument index="0" name="bus_layout" type="AudioBusLayout">
 			</argument>
 			<description>
+				Overwrites the currently used [AudioBusLayout].
 			</description>
 		</method>
 		<method name="set_bus_mute">
@@ -239,6 +265,7 @@
 			<argument index="1" name="enable" type="bool">
 			</argument>
 			<description>
+				If [code]true[/code] the bus at index [code]bus_idx[/code] is muted.
 			</description>
 		</method>
 		<method name="set_bus_name">
@@ -249,6 +276,7 @@
 			<argument index="1" name="name" type="String">
 			</argument>
 			<description>
+				Sets the name of the bus at index [code]bus_idx[/code] to [code]name[/code].
 			</description>
 		</method>
 		<method name="set_bus_send">
@@ -259,6 +287,7 @@
 			<argument index="1" name="send" type="String">
 			</argument>
 			<description>
+				Connects the output of the bus at [code]bus_idx[/code] to the bus named [code]send[/send].
 			</description>
 		</method>
 		<method name="set_bus_solo">
@@ -269,6 +298,7 @@
 			<argument index="1" name="enable" type="bool">
 			</argument>
 			<description>
+				If [code]true[/code] the bus at index [code]bus_idx[/code] is in solo mode.	
 			</description>
 		</method>
 		<method name="set_bus_volume_db">
@@ -279,6 +309,7 @@
 			<argument index="1" name="volume_db" type="float">
 			</argument>
 			<description>
+				Sets the volume of the bus at index [code]bus_idx[/code] to [code]volume_db[/code].
 			</description>
 		</method>
 		<method name="swap_bus_effects">
@@ -291,27 +322,33 @@
 			<argument index="2" name="by_effect_idx" type="int">
 			</argument>
 			<description>
+				Swaps the position of two effects in bus [code]bus_idx[/code].
 			</description>
 		</method>
 		<method name="unlock">
 			<return type="void">
 			</return>
 			<description>
+				Unlocks the audiodriver's main loop. After locking it always unlock it.
 			</description>
 		</method>
 	</methods>
 	<signals>
 		<signal name="bus_layout_changed">
 			<description>
+				Emitted when the [AudioBusLayout] changes.
 			</description>
 		</signal>
 	</signals>
 	<constants>
 		<constant name="SPEAKER_MODE_STEREO" value="0">
+			Two or fewer speakers are detected.
 		</constant>
 		<constant name="SPEAKER_SURROUND_51" value="2">
+			A 5.1 channel surround setup detected.
 		</constant>
 		<constant name="SPEAKER_SURROUND_71" value="3">
+			A 7.1 channel surround setup detected.
 		</constant>
 	</constants>
 </class>
diff --git a/doc/classes/AudioStreamPlayback.xml b/doc/classes/AudioStreamPlayback.xml
index 30a9a8f070d..f45beec42ca 100644
--- a/doc/classes/AudioStreamPlayback.xml
+++ b/doc/classes/AudioStreamPlayback.xml
@@ -1,8 +1,10 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioStreamPlayback" inherits="Reference" category="Core" version="3.0.alpha.custom_build">
 	<brief_description>
+		Meta class for playing back audio.
 	</brief_description>
 	<description>
+		Can play, loop, pause a scroll through Audio. See [AudioStream] and [AudioStreamOGGVorbis] for usage.
 	</description>
 	<tutorials>
 	</tutorials>
diff --git a/doc/classes/AudioStreamPlayer.xml b/doc/classes/AudioStreamPlayer.xml
index 9b104fe7576..1a9ad855655 100644
--- a/doc/classes/AudioStreamPlayer.xml
+++ b/doc/classes/AudioStreamPlayer.xml
@@ -7,6 +7,7 @@
 		Plays background audio.
 	</description>
 	<tutorials>
+		http://docs.godotengine.org/en/latest/learning/features/audio/index.html
 	</tutorials>
 	<demos>
 	</demos>
@@ -27,6 +28,7 @@
 			<return type="float">
 			</return>
 			<description>
+				Returns the position in the [AudioStream].
 			</description>
 		</method>
 		<method name="get_stream" qualifiers="const">
@@ -121,15 +123,16 @@
 	</methods>
 	<members>
 		<member name="autoplay" type="bool" setter="set_autoplay" getter="is_autoplay_enabled">
-			If [code]true[/code], audio plays when added to scene tree. Default value: [code]false[/code].
+			If [code]true[/code] audio plays when added to scene tree. Default value: [code]false[/code].
 		</member>
 		<member name="bus" type="String" setter="set_bus" getter="get_bus">
 			Bus on which this audio is playing.
 		</member>
 		<member name="mix_target" type="int" setter="set_mix_target" getter="get_mix_target" enum="AudioStreamPlayer.MixTarget">
+			If the audio configuration has more than two speakers, this sets the target channels. See [code]MIX_TARGET_*[/code] constants.
 		</member>
 		<member name="playing" type="bool" setter="_set_playing" getter="is_playing">
-			If [code]true[/code], audio is playing.
+			If [code]true[/code] audio is playing.
 		</member>
 		<member name="stream" type="AudioStream" setter="set_stream" getter="get_stream">
 			The [AudioStream] object to be played.
@@ -147,10 +150,13 @@
 	</signals>
 	<constants>
 		<constant name="MIX_TARGET_STEREO" value="0">
+			The audio will be played only on the first channel.
 		</constant>
 		<constant name="MIX_TARGET_SURROUND" value="1">
+			The audio will be played on all surround channels.
 		</constant>
 		<constant name="MIX_TARGET_CENTER" value="2">
+			The audio will be played on the second channel, which is usually the center.
 		</constant>
 	</constants>
 </class>
diff --git a/doc/classes/AudioStreamPlayer2D.xml b/doc/classes/AudioStreamPlayer2D.xml
index 600e0858dd9..c6fd8ff54fe 100644
--- a/doc/classes/AudioStreamPlayer2D.xml
+++ b/doc/classes/AudioStreamPlayer2D.xml
@@ -40,6 +40,7 @@
 			<return type="float">
 			</return>
 			<description>
+				Returns the position in the [AudioStream].
 			</description>
 		</method>
 		<method name="get_stream" qualifiers="const">
@@ -156,7 +157,7 @@
 			Dampens audio over distance with this as an exponent.
 		</member>
 		<member name="autoplay" type="bool" setter="set_autoplay" getter="is_autoplay_enabled">
-			If [code]true[/code], audio plays when added to scene tree. Default value: [code]false[/code].
+			If [code]true[/code] audio plays when added to scene tree. Default value: [code]false[/code].
 		</member>
 		<member name="bus" type="String" setter="set_bus" getter="get_bus">
 			Bus on which this audio is playing.
@@ -165,7 +166,7 @@
 			Maximum distance from which audio is still hearable.
 		</member>
 		<member name="playing" type="bool" setter="_set_playing" getter="is_playing">
-			If [code]true[/code], audio is playing.
+			If [code]true[/code] audio is playing.
 		</member>
 		<member name="stream" type="AudioStream" setter="set_stream" getter="get_stream">
 			The [AudioStream] object to be played.
diff --git a/doc/classes/AudioStreamPlayer3D.xml b/doc/classes/AudioStreamPlayer3D.xml
index 886b2b975a8..2085b35e2e7 100644
--- a/doc/classes/AudioStreamPlayer3D.xml
+++ b/doc/classes/AudioStreamPlayer3D.xml
@@ -82,6 +82,7 @@
 			<return type="float">
 			</return>
 			<description>
+				Returns the position in the [AudioStream].
 			</description>
 		</method>
 		<method name="get_stream" qualifiers="const">
@@ -288,7 +289,7 @@
 			Decides if audio should get quieter with distance linearly, quadratically or logarithmically.
 		</member>
 		<member name="autoplay" type="bool" setter="set_autoplay" getter="is_autoplay_enabled">
-			If [code]true[/code], audio plays audio plays when added to scene tree. Default value: [code]false[/code].
+			If [code]true[/code] audio plays when added to scene tree. Default value: [code]false[/code].
 		</member>
 		<member name="bus" type="String" setter="set_bus" getter="get_bus">
 			Bus on which this audio is playing.
@@ -300,7 +301,7 @@
 			The angle in which the audio reaches cameras undampened.
 		</member>
 		<member name="emission_angle_enabled" type="bool" setter="set_emission_angle_enabled" getter="is_emission_angle_enabled">
-			If [code]true[/code], the audio should be dampened according to the direction of the sound.
+			If [code]true[/code] the audio should be dampened according to the direction of the sound.
 		</member>
 		<member name="emission_angle_filter_attenuation_db" type="float" setter="set_emission_angle_filter_attenuation_db" getter="get_emission_angle_filter_attenuation_db">
 			dampens audio if camera is outside of 'emission_angle_degrees' and 'emission_angle_enabled' is set by this factor, in dB.