From 6fe6a3733b5db15cfa58f8f755dd90c9aa206558 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Wed, 15 Jun 2022 09:51:43 -0400
Subject: [PATCH] SDL_mixer.h: Made a single function doxygen/wikiheaders.pl
friendly.
Just an example of how this will have to change for the wiki bridge.
---
include/SDL_mixer.h | 33 ++++++++++++++++++++++++---------
1 file changed, 24 insertions(+), 9 deletions(-)
diff --git a/include/SDL_mixer.h b/include/SDL_mixer.h
index 9cb20e51..22b012d9 100644
--- a/include/SDL_mixer.h
+++ b/include/SDL_mixer.h
@@ -385,30 +385,45 @@ extern DECLSPEC int SDLCALL Mix_UnregisterAllEffects(int channel);
*/
-/* Set the panning of a channel. The left and right channels are specified
- * as integers between 0 and 255, quietest to loudest, respectively.
+/**
+ * Set the panning of a channel.
+ *
+ * The left and right channels are specified as integers between 0 and 255,
+ * quietest to loudest, respectively.
*
* Technically, this is just individual volume control for a sample with
* two (stereo) channels, so it can be used for more than just panning.
* If you want real panning, call it like this:
*
- * Mix_SetPanning(channel, left, 255 - left);
+ * ```c
+ * Mix_SetPanning(channel, left, 255 - left);
+ * ```
*
* ...which isn't so hard.
*
- * Setting (channel) to MIX_CHANNEL_POST registers this as a posteffect, and
+ * Setting `channel` to MIX_CHANNEL_POST registers this as a posteffect, and
* the panning will be done to the final mixed stream before passing it on
* to the audio device.
*
* This uses the Mix_RegisterEffect() API internally, and returns without
* registering the effect function if the audio device is not configured
- * for stereo output. Setting both (left) and (right) to 255 causes this
+ * for stereo output. Setting both `left` and `right` to 255 causes this
* effect to be unregistered, since that is the data's normal state.
*
- * returns zero if error (no such channel or Mix_RegisterEffect() fails),
- * nonzero if panning effect enabled. Note that an audio device in mono
- * mode is a no-op, but this call will return successful in that case.
- * Error messages can be retrieved from Mix_GetError().
+ * Note that an audio device in mono mode is a no-op, but this call will
+ * return successful in that case. Error messages can be retrieved from
+ * Mix_GetError().
+ *
+ * \param channel The mixer channel to pan or MIX_CHANNEL_POST.
+ * \param left Volume of stereo left channel, 0 is silence, 255 is full volume.
+ * \param right Volume of stereo right channel, 0 is silence, 255 is full volume.
+ * \returns zero if error (no such channel or Mix_RegisterEffect() fails),
+ * nonzero if panning effect enabled.
+ *
+ * \since This function is available since SDL_mixer 2.0.0.
+ *
+ * \sa Mix_SetPosition
+ * \sa Mix_SetDistance
*/
extern DECLSPEC int SDLCALL Mix_SetPanning(int channel, Uint8 left, Uint8 right);