Update documentation.

miniaudio.h

@@ -4032,93 +4032,182 @@ ma_result ma_device_init_ex(const ma_backend backends[], ma_uint32 backendCount,
 /*
 Uninitializes a device.
 
-This will explicitly stop the device. You do not need to call ma_device_stop() beforehand, but it's
+This will explicitly stop the device. You do not need to call `ma_device_stop()` beforehand, but it's harmless if you do.
-harmless if you do.
 
-Do not call this in any callback.
 
-Return Value:
+Parameters
-  MA_SUCCESS if successful; any other error code otherwise.
+----------
+pDevice (in)
+    A pointer to the device to stop.
 
-Thread Safety: UNSAFE
-  As soon as this API is called the device should be considered undefined. All bets are off if you
-  try using the device at the same time as uninitializing it.
 
-Callback Safety: UNSAFE
+Return Value
-  It is not safe to call this inside any callback. Doing this will result in a deadlock.
+------------
+MA_SUCCESS if successful; any other error code otherwise.
+
+
+Thread Safety
+-------------
+Unsafe. As soon as this API is called the device should be considered undefined.
+
+
+Callback Safety
+---------------
+Unsafe. It is not safe to call this inside any callback. Doing this will result in a deadlock.
+
+
+See Also
+--------
+ma_device_init()
+ma_device_stop()
 */
 void ma_device_uninit(ma_device* pDevice);
 
 /*
 Sets the callback to use when the device has stopped, either explicitly or as a result of an error.
 
-Thread Safety: SAFE
+
-  This API is implemented as a simple atomic assignment.
+Parameters
+----------
+pDevice (in)
+    A pointer to the device whose stop callback is getting set.
+
+onStop (in, nullable)
+    The new stop callback. Can be null.
+
+
+Thread Safety
+-------------
+Safe. This API is implemented as a simple atomic assignment.
+
+
+Callback Safety
+---------------
+Safe. This is just a simple assignment.
 */
-void ma_device_set_stop_callback(ma_device* pDevice, ma_stop_proc proc);
+void ma_device_set_stop_callback(ma_device* pDevice, ma_stop_proc onStop);
 
 /*
-Activates the device. For playback devices this begins playback. For capture devices it begins
+Starts the device. For playback devices this begins playback. For capture devices it begins recording.
-recording.
 
-For a playback device, this will retrieve an initial chunk of audio data from the client before
+Use `ma_device_stop()` to stop the device.
-returning. The reason for this is to ensure there is valid audio data in the buffer, which needs
-to be done _before_ the device begins playback.
 
-This API waits until the backend device has been started for real by the worker thread. It also
+
-waits on a mutex for thread-safety.
+Parameters
+----------
+pDevice (in)
+    A pointer to the device to start.
+
+
+Return Value
+------------
+MA_SUCCESS if successful; any other error code otherwise.
+
+
+Thread Safety
+-------------
+Safe. It's safe to call this from any thread with the exception of the callback thread.
+
+
+Callback Safety
+---------------
+Unsafe. It is not safe to call this inside any callback.
+
+
+Remarks
+-------
+For a playback device, this will retrieve an initial chunk of audio data from the client before returning. The reason for this is to ensure there is valid
+audio data in the buffer, which needs to be done before the device begins playback.
+
+This API waits until the backend device has been started for real by the worker thread. It also waits on a mutex for thread-safety.
 
 Do not call this in any callback.
 
-Return Value:
-  MA_SUCCESS if successful; any other error code otherwise.
 
-Thread Safety: SAFE
+See Also
-  It's safe to call this from any thread with the exception of the callback thread.
+--------
-
+ma_device_stop()
-Callback Safety: UNSAFE
-  It is not safe to call this inside any callback.
 */
 ma_result ma_device_start(ma_device* pDevice);
 
 /*
-Puts the device to sleep, but does not uninitialize it. Use ma_device_start() to start it up again.
+Stops the device. For playback devices this stops playback. For capture devices it stops recording.
 
-This API needs to wait on the worker thread to stop the backend device properly before returning. It
+Use `ma_device_start()` to start the device again.
-also waits on a mutex for thread-safety. In addition, some backends need to wait for the device to
-finish playback/recording of the current fragment which can take some time (usually proportionate to
-the buffer size that was specified at initialization time).
 
-This should not drop unprocessed samples. Backends are required to either pause the stream in-place
+
-or drain the buffer if pausing is not possible. The reason for this is that stopping the device and
+Parameters
-the resuming it with ma_device_start() (which you might do when your program loses focus) may result
+----------
-in a situation where those samples are never output to the speakers or received from the microphone
+pDevice (in)
-which can in turn result in de-syncs.
+    A pointer to the device to stop.
+
+
+Return Value
+------------
+MA_SUCCESS if successful; any other error code otherwise.
+
+
+Thread Safety
+-------------
+Safe. It's safe to call this from any thread with the exception of the callback thread.
+
+
+Callback Safety
+---------------
+Unsafe. It is not safe to call this inside any callback. Doing this will result in a deadlock.
+
+
+Remarks
+-------
+This API needs to wait on the worker thread to stop the backend device properly before returning. It also waits on a mutex for thread-safety. In addition, some
+backends need to wait for the device to finish playback/recording of the current fragment which can take some time (usually proportionate to the buffer size
+that was specified at initialization time).
+
+Backends are required to either pause the stream in-place or drain the buffer if pausing is not possible. The reason for this is that stopping the device and
+the resuming it with ma_device_start() (which you might do when your program loses focus) may result in a situation where those samples are never output to the
+speakers or received from the microphone which can in turn result in de-syncs.
 
 Do not call this in any callback.
 
-Return Value:
+This will be called implicitly by `ma_device_uninit()`.
-  MA_SUCCESS if successful; any other error code otherwise.
 
-Thread Safety: SAFE
-  It's safe to call this from any thread with the exception of the callback thread.
 
-Callback Safety: UNSAFE
+See Also
-  It is not safe to call this inside any callback. Doing this will result in a deadlock.
+--------
+ma_device_start()
 */
 ma_result ma_device_stop(ma_device* pDevice);
 
 /*
 Determines whether or not the device is started.
 
-This is implemented as a simple accessor.
 
-Return Value:
+Parameters
-  True if the device is started, false otherwise.
+----------
+pDevice (in)
+    A pointer to the device whose start state is being retrieved.
 
-Thread Safety: SAFE
+
-  If another thread calls ma_device_start() or ma_device_stop() at this same time as this function
+Return Value
-  is called, there's a very small chance the return value will be out of sync.
+------------
+True if the device is started, false otherwise.
+
+
+Thread Safety
+-------------
+Safe. If another thread calls `ma_device_start()` or `ma_device_stop()` at this same time as this function is called, there's a very small chance the return
+value will be out of sync.
+
+
+Callback Safety
+---------------
+Safe. This is implemented as a simple accessor.
+
+
+See Also
+--------
+ma_device_start()
+ma_device_stop()
 */
 ma_bool32 ma_device_is_started(ma_device* pDevice);
 
@@ -28259,13 +28348,13 @@ void ma_device_uninit(ma_device* pDevice)
     MA_ZERO_OBJECT(pDevice);
 }
 
-void ma_device_set_stop_callback(ma_device* pDevice, ma_stop_proc proc)
+void ma_device_set_stop_callback(ma_device* pDevice, ma_stop_proc onStop)
 {
     if (pDevice == NULL) {
         return;
     }
 
-    ma_atomic_exchange_ptr(&pDevice->onStop, proc);
+    ma_atomic_exchange_ptr(&pDevice->onStop, onStop);
 }
 
 ma_result ma_device_start(ma_device* pDevice)