Overhaul AudioStreamPlayer's documentation

[Mickeon]

Closes #76324.
Documents #71122 's behavior.

Continuation of similar past efforts with the same goal of refreshing the documentation up a notch.

AudioStreamPlayer's reference smelled old. A lot of information is missing. Not everything has to be documented, of course. That would severely impact readability, by making the class look more complicated than it actually is. This is a pretty common class for most users, and we have got to be careful.

PRs for AudioStreamPlayer2D and AudioStreamPlayer3D will come at a later date, after this one is merged.

---

• The wording now matches other classes are documented a lot more closely;
• A lot of missing information is added;
  • Unfortunately, unlike previous PRs, a bit of extra verbosity is necessary;
• Mention the ability to play more than one sound more clearly thorough the reference;
• Mention the importance of the stream property;
• Mention when the finished signal is emitted more explicitly;
  • The previous description failed to explain when this signal was not emitted, as much as it may seem like it should.
• Add note about MIX_TARGET_STEREO being the default mix target.

---

Methods

get_playback_position

• Imply there can be more than one AudioStreamPlayback (sound);
• Mention return value when no sounds are playing;
• Add note about Audio playback progress times are not updated in real time #71122.

get_stream_playback

• Mention the error when no sounds are played (AudioStreamPlayer.get_stream_playback() returns null #76324);
• Imply there can be more than one AudioStreamPlayback.

has_stream_playback

• Simplify when this method returns true;

play

• Be a little more explicit.
  • The original description quickly talks about the optional parameter. It doesn't make much sense to me, given that it's entirely optional.

seek

• Be a little more explicit;
• Imply there can be more than one AudioStreamPlayback (sound).

stop

• Be a little more explicit.

  • "Stops all audio" is it like... my entire system becomes deaf or something?

---

Properties

autoplay

• Be a little more explicit.
  • The previous description was fairly awkward.

bus

• Simplified the note considerably.
  • What a mouthful... More experienced users already know the bus layout can be changed. It's also overwhelming information for AudioStreamPlayer. It's only necessary to describe the fall back behavior.

max_polyphony

• Be a little more explicit.

mix_target

• Shuffled wording around to be clearer;
• Mention how to get the configured speaker mode yourself.

pitch_scale

• Add example on how this property affects the audio.

playing

• Describe what happens when setting this property.

stream

• Describe what happens when setting this property.

stream_paused

• Imply there can be more than one AudioStreamPlayback (sound).
• Mention that this property is changed automatically on a bunch of occasions.
  • I can't find it, but I believe there was an issue about this.

volume_db

• Be a little more explicit.
  • The concept of audio volume is so widely understood it probably doesn't need further explanations. (such as "Higher values make the sound louder"). This is fine.
• Add note about the linear/db conversion functions.

---

I don't think this PR is fully complete. The leading description needs a bit more to it. But, I wanted to express this PR's intentions as soon as possible. Feedback is very, very welcome.

In particular, I attempted to reduce verbosity by replacing "audio" when referring to the individual AudioStreamPlaybacks with "sounds". Saying "playback" all the time does not quite convince me as it's repetitive, and is not something that the common user will ever have to think about, so it's a puzzling situation.

[Mickeon]

Updated PR to apply most of the aforementioned suggestions.

[ronyeh]

Looks good. Improving documentation is very valuable work, and helps out new developers!

[Mickeon]

Rebased after minor conflict. Would be nice for this to be looked at sooner than later, so that both AudioStreamPlayer2D and AudioStreamPlayer3D may receive a similar treatment

[akien-mga]

Thanks!