[AD] Patch: Audio addon docs corrections

[Polybios <polybios@xxxxxxxxxx>]

Hi everyone,

finally, I've managed to have a look at the docs for the audio addon.

Attached is a patch with
1. corrections / clarifications
2. addition of some short introductory paragraphs; it looks like a lot 
of text, but it actually isn't - the addon itself is just rather extensive.

I hope this makes some sense - do what you like with it.

One API thing: al_set_sample_instance_length appears to be a bit odd. At 
first, I thought the getters of _channels, _depth, _frequency and 
_length on sample instances were merely a "passthrough" to query the 
underlying sample. However, _length is the only one of these properties 
with a setter on the sample instance. The use case I see (and tried) is 
to play only parts of the sample. However, it has no effect when 
playmode is set to loop. Plus, when you pass a length that is larger 
than the actual sample, it will continue playing static/noise and 
finally crash. I'm not exactly sure if that's the way it should be.

Another API suggestion: Maybe it would be nice to introduce an alias for 
al_restore_default_mixer called al_create_default_mixer, since it could 
well make sense to call it during initialization to create a 1 voice/1 
mixer setup (without al_play_sample in mind). Calling a function named 
"restore" during initialization would be a bit awkward, as would be 
al_reserve_samples(0). Not really important, though.

By the way, there's a small bug with the new "View Source code"-feature 
of the docs when the function has a multi-line declaration (the link 
under "al_play_sample" will show the problem).

Thanks and kind regards
Polybios