docs: add more documentation to each of the modules in vlib (#13043)

vlib/sokol/audio/audio.v

@@ -12,9 +12,37 @@ $if linux {
 #flag darwin -framework AudioToolbox
 #flag windows -lole32
 
+// callback function for `stream_cb` in [[C.saudio_desc](#C.saudio_desc)] when calling [audio.setup()](#setup)
 //
+// sokol callback functions run in a separate thread
+//
+// This function will be called with a reference to the C buffer and the maximum number of frames and channels
+// the audio backend is expecting in its buffer.
+//
+// Terms:
+// - *sample* - a 32-bit floating point number from `-1.0` to `+1.0` representing the waveform amplitude at that instant
+// - *frame* - one sample for each channel at that instant
+//
+// To determine the number of samples expected, do `num_frames * num_channels`.
+// Then, write up to that many `f32` samples into `buffer` using unsafe operations.
+//
+// Do not write more data to the buffer than it is requesting, but you may write less. The buffer is initialized with
+// zeroes, so unwritten data will result in audio silence.
+// Example: unsafe { C.memcpy(buffer, &samples, samples.len * int(sizeof(f32))) }
+// Example: unsafe { mut b := buffer; for i, sample in samples { b[i] = sample } }
 pub type FNStreamingCB = fn (buffer &f32, num_frames int, num_channels int)
 
+// callback function for `stream_userdata_cb` to use in `C.saudio_desc` when calling [audio.setup()](#setup)
+//
+// sokol callback functions run in a separate thread
+//
+// This function operates the same way as [[FNStreamingCB](#FNStreamingCB)] but it passes customizable `user_data` to the
+// callback. This is the method to use if your audio data is stored in a struct or array. Identify the
+// `user_data` when you call `audio.setup()` and that object will be passed to the callback as the last arg.
+// Example: mut soundbuffer := []f32
+// Example: soundbuffer << previously_parsed_wavfile_bytes
+// Example: audio.setup(stream_userdata_cb: mycallback, user_data: soundbuffer)
+// Example: fn mycallback(buffer &f32, num_frames int, num_channels int, mut sb []f32) { ... }
 pub type FnStreamingCBWithUserData = fn (buffer &f32, num_frames int, num_channels int, user_data voidptr)
 
 pub fn (x FNStreamingCB) str() string {
@@ -25,7 +53,17 @@ pub fn (x FnStreamingCBWithUserData) str() string {
 	return '&FnStreamingCBWithUserData{ ${ptr_str(x)} }'
 }
 
+// only one of `stream_cb` or `stream_userdata_cb` should be used
 //
+// default values (internal to sokol C library):
+//
+// | variable      | default  | note |
+// | :-----------  | -------: | :--------- |
+// | sample_rate   | 44100    | higher sample rates take more memory but are higher quality |
+// | num_channels  | 1        | for stereo sound, this should be 2 |
+// | buffer_frames | 2048     | buffer size in frames, larger is more latency, smaller means higher CPU |
+// | packet_frames | 128      | push model only, number of frames that will be pushed in each packet |
+// | num_packets   | 64       | for push model only, number of packets in the backend ringbuffer |
 pub struct C.saudio_desc {
 	sample_rate        int
 	num_channels       int
@@ -84,17 +122,17 @@ pub fn query() C.saudio_desc {
 	return C.saudio_query_desc()
 }
 
-// audio.sample_rate - actual sample rate
+// audio.sample_rate - return the actual sample rate
 pub fn sample_rate() int {
 	return C.saudio_sample_rate()
 }
 
-// audio.buffer_frames - return actual backend buffer size in number of frames
+// audio.buffer_frames - return the actual backend buffer size in number of frames
 pub fn buffer_frames() int {
 	return C.saudio_buffer_frames()
 }
 
-// audio.channels - actual number of channels
+// audio.channels - return the actual number of channels
 pub fn channels() int {
 	return C.saudio_channels()
 }
@@ -105,7 +143,7 @@ pub fn suspended() bool {
 	return C.saudio_suspended()
 }
 
-// audio.expect - get current number of frames to fill packet queue; use in combination with audio.push/2
+// audio.expect - get current number of frames to fill packet queue; use in combination with audio.push
 pub fn expect() int {
 	return C.saudio_expect()
 }
@@ -115,7 +153,8 @@ pub fn push(frames &f32, num_frames int) int {
 	return C.saudio_push(frames, num_frames)
 }
 
-//
+// audio.fclamp - helper function to 'clamp' a number to a certain range
+// Example: realsample := audio.fclamp(sample, -1.0, 1.0)
 [inline]
 pub fn fclamp(x f32, flo f32, fhi f32) f32 {
 	if x > fhi {
@@ -127,6 +166,10 @@ pub fn fclamp(x f32, flo f32, fhi f32) f32 {
 	return x
 }
 
+// audio.min - helper function to return the smaller of two numbers
+//
+// math.min returns `f32` values, this returns `int` values
+// Example: smaller := audio.min(1, 5) // smaller == 1
 pub fn min(x int, y int) int {
 	if x < y {
 		return x
@@ -134,6 +177,10 @@ pub fn min(x int, y int) int {
 	return y
 }
 
+// audio.max - helper function to return the larger of two numbers
+//
+// math.max returns `f32` values, this returns `int` values
+// Example: larger := audio.max(1, 5) // larger == 5
 pub fn max(x int, y int) int {
 	if x < y {
 		return y