Merge pull request #1043 from GuillaumeGomez/doc-aliases

Add doc aliases for C equivalents

src/sdl2/audio.rs

@@ -101,6 +101,7 @@ impl AudioSubsystem {
         AudioQueue::open_queue(self, device, spec)
     }
 
+    #[doc(alias = "SDL_GetCurrentAudioDriver")]
     pub fn current_audio_driver(&self) -> &'static str {
         unsafe {
             let buf = sys::SDL_GetCurrentAudioDriver();
@@ -110,6 +111,7 @@ impl AudioSubsystem {
         }
     }
 
+    #[doc(alias = "SDL_GetNumAudioDevices")]
     pub fn num_audio_playback_devices(&self) -> Option<u32> {
         let result = unsafe { sys::SDL_GetNumAudioDevices(0) };
         if result < 0 {
@@ -120,6 +122,7 @@ impl AudioSubsystem {
         }
     }
 
+    #[doc(alias = "SDL_GetAudioDeviceName")]
     pub fn audio_playback_device_name(&self, index: u32) -> Result<String, String> {
         unsafe {
             let dev_name = sys::SDL_GetAudioDeviceName(index as c_int, 0);
@@ -176,6 +179,7 @@ impl AudioFormat {
         }
     }
 
+    #[doc(alias = "SDL_AudioFormat")]
     fn to_ll(self) -> sys::SDL_AudioFormat {
         self as sys::SDL_AudioFormat
     }
@@ -228,6 +232,7 @@ impl TryFrom<u32> for AudioStatus {
     }
 }
 
+#[doc(alias = "SDL_GetAudioDriver")]
 #[derive(Copy, Clone)]
 pub struct DriverIterator {
     length: i32,
@@ -262,6 +267,7 @@ impl Iterator for DriverIterator {
 impl ExactSizeIterator for DriverIterator { }
 
 /// Gets an iterator of all audio drivers compiled into the SDL2 library.
+#[doc(alias = "SDL_GetAudioDriver")]
 #[inline]
 pub fn drivers() -> DriverIterator {
     // This function is thread-safe and doesn't require the audio subsystem to be initialized.
@@ -290,6 +296,7 @@ impl AudioSpecWAV {
     }
 
     /// Loads a WAVE from the data source.
+    #[doc(alias = "SDL_LoadWAV_RW")]
     pub fn load_wav_rw(src: &mut RWops) -> Result<AudioSpecWAV, String> {
         use std::mem::MaybeUninit;
         use std::ptr::null_mut;
@@ -325,6 +332,7 @@ impl AudioSpecWAV {
 }
 
 impl Drop for AudioSpecWAV {
+    #[doc(alias = "SDL_FreeWAV")]
     fn drop(&mut self) {
         unsafe { sys::SDL_FreeWAV(self.audio_buf); }
     }
@@ -532,6 +540,7 @@ impl AudioDeviceID {
 }
 
 impl Drop for AudioDeviceID {
+    #[doc(alias = "SDL_CloseAudioDevice")]
     fn drop(&mut self) {
         //! Shut down audio processing and close the audio device.
         unsafe { sys::SDL_CloseAudioDevice(self.id()) }
@@ -548,6 +557,7 @@ pub struct AudioQueue<Channel: AudioFormatNum> {
 
 impl<'a, Channel: AudioFormatNum> AudioQueue<Channel> {
     /// Opens a new audio device given the desired parameters and callback.
+    #[doc(alias = "SDL_OpenAudioDevice")]
     pub fn open_queue<D: Into<Option<&'a str>>>(a: &AudioSubsystem, device: D, spec: &AudioSpecDesired) -> Result<AudioQueue<Channel>, String> {
         use std::mem::MaybeUninit;
 
@@ -590,6 +600,7 @@ impl<'a, Channel: AudioFormatNum> AudioQueue<Channel> {
     }
 
     #[inline]
+    #[doc(alias = "SDL_GetAudioDeviceStatus")]
     pub fn subsystem(&self) -> &AudioSubsystem { &self.subsystem }
 
     #[inline]
@@ -603,26 +614,31 @@ impl<'a, Channel: AudioFormatNum> AudioQueue<Channel> {
     }
 
     /// Pauses playback of the audio device.
+    #[doc(alias = "SDL_PauseAudioDevice")]
     pub fn pause(&self) {
         unsafe { sys::SDL_PauseAudioDevice(self.device_id.id(), 1) }
     }
 
     /// Starts playback of the audio device.
+    #[doc(alias = "SDL_PauseAudioDevice")]
     pub fn resume(&self) {
         unsafe { sys::SDL_PauseAudioDevice(self.device_id.id(), 0) }
     }
 
     /// Adds data to the audio queue.
+    #[doc(alias = "SDL_QueueAudio")]
     pub fn queue(&self, data: &[Channel]) -> bool {
         let result = unsafe {sys::SDL_QueueAudio(self.device_id.id(), data.as_ptr() as *const c_void, (data.len() * mem::size_of::<Channel>()) as u32)};
         result == 0
     }
 
+    #[doc(alias = "SDL_GetQueuedAudioSize")]
     pub fn size(&self) -> u32 {
         unsafe {sys::SDL_GetQueuedAudioSize(self.device_id.id())}
     }
 
     /// Clears all data from the current audio queue.
+    #[doc(alias = "SDL_ClearQueuedAudio")]
     pub fn clear(&self) {
         unsafe {sys::SDL_ClearQueuedAudio(self.device_id.id());}
     }
@@ -639,6 +655,7 @@ pub struct AudioDevice<CB: AudioCallback> {
 
 impl<CB: AudioCallback> AudioDevice<CB> {
     /// Opens a new audio device for playback or capture (given the desired parameters and callback).
+    #[doc(alias = "SDL_OpenAudioDevice")]
     fn open<'a, F, D>(a: &AudioSubsystem, device: D, spec: &AudioSpecDesired, get_callback: F, capture: bool) -> Result<AudioDevice <CB>, String>
     where
         F: FnOnce(AudioSpec) -> CB,
@@ -713,6 +730,7 @@ impl<CB: AudioCallback> AudioDevice<CB> {
     }
 
     #[inline]
+    #[doc(alias = "SDL_GetAudioDeviceStatus")]
     pub fn subsystem(&self) -> &AudioSubsystem { &self.subsystem }
 
     #[inline]
@@ -726,11 +744,13 @@ impl<CB: AudioCallback> AudioDevice<CB> {
     }
 
     /// Pauses playback of the audio device.
+    #[doc(alias = "SDL_PauseAudioDevice")]
     pub fn pause(&self) {
         unsafe { sys::SDL_PauseAudioDevice(self.device_id.id(), 1) }
     }
 
     /// Starts playback of the audio device.
+    #[doc(alias = "SDL_PauseAudioDevice")]
     pub fn resume(&self) {
         unsafe { sys::SDL_PauseAudioDevice(self.device_id.id(), 0) }
     }
@@ -740,6 +760,7 @@ impl<CB: AudioCallback> AudioDevice<CB> {
     /// When the returned lock guard is dropped, `SDL_UnlockAudioDevice` is
     /// called.
     /// Use this method to read and mutate callback data.
+    #[doc(alias = "SDL_LockAudioDevice")]
     pub fn lock(&mut self) -> AudioDeviceLockGuard<CB> {
         unsafe { sys::SDL_LockAudioDevice(self.device_id.id()) };
         AudioDeviceLockGuard {
@@ -766,6 +787,7 @@ pub struct AudioDeviceLockGuard<'a, CB> where CB: AudioCallback, CB: 'a {
 
 impl<'a, CB: AudioCallback> Deref for AudioDeviceLockGuard<'a, CB> {
     type Target = CB;
+    #[doc(alias = "SDL_UnlockAudioDevice")]
     fn deref(&self) -> &CB { (*self.device.userdata).as_ref().expect("Missing callback") }
 }
 
@@ -785,6 +807,7 @@ pub struct AudioCVT {
 }
 
 impl AudioCVT {
+    #[doc(alias = "SDL_BuildAudioCVT")]
     pub fn new(src_format: AudioFormat, src_channels: u8, src_rate: i32,
                dst_format: AudioFormat, dst_channels: u8, dst_rate: i32) -> Result<AudioCVT, String>
     {
@@ -805,6 +828,7 @@ impl AudioCVT {
         }
     }
 
+    #[doc(alias = "SDL_ConvertAudio")]
     pub fn convert(&self, mut src: Vec<u8>) -> Vec<u8> {
         //! Convert audio data to a desired audio format.
         //!

src/sdl2/clipboard.rs

@@ -29,6 +29,7 @@ impl crate::VideoSubsystem {
 }
 
 impl ClipboardUtil {
+    #[doc(alias = "SDL_SetClipboardText")]
     pub fn set_clipboard_text(&self, text: &str) -> Result<(), String> {
         unsafe {
             let text = CString::new(text).unwrap();
@@ -42,6 +43,7 @@ impl ClipboardUtil {
         }
     }
 
+    #[doc(alias = "SDL_GetClipboardText")]
     pub fn clipboard_text(&self) -> Result<String, String> {
         unsafe {
             let buf = sys::SDL_GetClipboardText();
@@ -56,6 +58,7 @@ impl ClipboardUtil {
         }
     }
 
+    #[doc(alias = "SDL_HasClipboardText")]
     pub fn has_clipboard_text(&self) -> bool {
         unsafe { sys::SDL_HasClipboardText() == sys::SDL_bool::SDL_TRUE }
     }

src/sdl2/controller.rs

@@ -50,6 +50,7 @@ impl error::Error for AddMappingError {
 
 impl GameControllerSubsystem {
     /// Retrieve the total number of attached joysticks *and* controllers identified by SDL.
+    #[doc(alias = "SDL_NumJoysticks")]
     pub fn num_joysticks(&self) -> Result<u32, String> {
         let result = unsafe { sys::SDL_NumJoysticks() };
 
@@ -62,6 +63,7 @@ impl GameControllerSubsystem {
 
     /// Return true if the joystick at index `joystick_index` is a game controller.
     #[inline]
+    #[doc(alias = "SDL_IsGameController")]
     pub fn is_game_controller(&self, joystick_index: u32) -> bool {
         match validate_int(joystick_index, "joystick_index") {
             Ok(joystick_index) => unsafe { sys::SDL_IsGameController(joystick_index) != sys::SDL_bool::SDL_FALSE },
@@ -72,6 +74,7 @@ impl GameControllerSubsystem {
     /// Attempt to open the controller at index `joystick_index` and return it.
     /// Controller IDs are the same as joystick IDs and the maximum number can
     /// be retrieved using the `SDL_NumJoysticks` function.
+    #[doc(alias = "SDL_GameControllerOpen")]
     pub fn open(&self, joystick_index: u32) -> Result<GameController, IntegerOrSdlError> {
         use crate::common::IntegerOrSdlError::*;
         let joystick_index = validate_int(joystick_index, "joystick_index")?;
@@ -88,6 +91,7 @@ impl GameControllerSubsystem {
     }
 
     /// Return the name of the controller at index `joystick_index`.
+    #[doc(alias = "SDL_GameControllerNameForIndex")]
     pub fn name_for_index(&self, joystick_index: u32) -> Result<String, IntegerOrSdlError> {
         use crate::common::IntegerOrSdlError::*;
         let joystick_index = validate_int(joystick_index, "joystick_index")?;
@@ -104,17 +108,20 @@ impl GameControllerSubsystem {
 
     /// If state is `true` controller events are processed, otherwise
     /// they're ignored.
+    #[doc(alias = "SDL_GameControllerEventState")]
     pub fn set_event_state(&self, state: bool) {
         unsafe { sys::SDL_GameControllerEventState(state as i32) };
     }
 
     /// Return `true` if controller events are processed.
+    #[doc(alias = "SDL_GameControllerEventState")]
     pub fn event_state(&self) -> bool {
         unsafe { sys::SDL_GameControllerEventState(sys::SDL_QUERY as i32)
                  == sys::SDL_ENABLE as i32 }
     }
 
     /// Add a new controller input mapping from a mapping string.
+    #[doc(alias = "SDL_GameControllerAddMapping")]
     pub fn add_mapping(&self, mapping: &str)
             -> Result<MappingStatus, AddMappingError> {
         use self::AddMappingError::*;
@@ -153,6 +160,7 @@ impl GameControllerSubsystem {
     }
 
     /// Load controller input mappings from an SDL [`RWops`] object.
+    #[doc(alias = "SDL_GameControllerAddMappingsFromRW")]
     pub fn load_mappings_from_rw<'a>(&self, rw: RWops<'a>) -> Result<i32, AddMappingError> {
         use self::AddMappingError::*;
 
@@ -163,6 +171,7 @@ impl GameControllerSubsystem {
         }
     }
 
+    #[doc(alias = "SDL_GameControllerMappingForGUID")]
     pub fn mapping_for_guid(&self, guid: joystick::Guid) -> Result<String, String> {
         let c_str = unsafe { sys::SDL_GameControllerMappingForGUID(guid.raw()) };
 
@@ -171,6 +180,7 @@ impl GameControllerSubsystem {
 
     #[inline]
     /// Force controller update when not using the event loop
+    #[doc(alias = "SDL_GameControllerUpdate")]
     pub fn update(&self) {
         unsafe { sys::SDL_GameControllerUpdate() };
     }
@@ -190,6 +200,7 @@ pub enum Axis {
 impl Axis {
     /// Return the Axis from a string description in the same format
     /// used by the game controller mapping strings.
+    #[doc(alias = "SDL_GameControllerGetAxisFromString")]
     pub fn from_string(axis: &str) -> Option<Axis> {
         let id = match CString::new(axis) {
             Ok(axis) => unsafe { sys::SDL_GameControllerGetAxisFromString(axis.as_ptr() as *const c_char) },
@@ -202,6 +213,7 @@ impl Axis {
 
     /// Return a string for a given axis in the same format using by
     /// the game controller mapping strings
+    #[doc(alias = "SDL_GameControllerGetStringForAxis")]
     pub fn string(self) -> String {
         let axis: sys::SDL_GameControllerAxis;
         unsafe { axis = transmute(self); }
@@ -259,6 +271,7 @@ pub enum Button {
 impl Button {
     /// Return the Button from a string description in the same format
     /// used by the game controller mapping strings.
+    #[doc(alias = "SDL_GameControllerGetButtonFromString")]
     pub fn from_string(button: &str) -> Option<Button> {
         let id = match CString::new(button) {
             Ok(button) => unsafe { sys::SDL_GameControllerGetButtonFromString(button.as_ptr() as *const c_char) },
@@ -271,6 +284,7 @@ impl Button {
 
     /// Return a string for a given button in the same format using by
     /// the game controller mapping strings
+    #[doc(alias = "SDL_GameControllerGetStringForButton")]
     pub fn string(self) -> String {
         let button: sys::SDL_GameControllerButton;
         unsafe { button = transmute(self); }
@@ -342,6 +356,7 @@ impl GameController {
 
     /// Return the name of the controller or an empty string if no
     /// name is found.
+    #[doc(alias = "SDL_GameControllerName")]
     pub fn name(&self) -> String {
         let name = unsafe { sys::SDL_GameControllerName(self.raw) };
 
@@ -350,6 +365,7 @@ impl GameController {
 
     /// Return a String describing the controller's button and axis
     /// mappings
+    #[doc(alias = "SDL_GameControllerMapping")]
     pub fn mapping(&self) -> String {
         let mapping = unsafe { sys::SDL_GameControllerMapping(self.raw) };
 
@@ -358,11 +374,13 @@ impl GameController {
 
     /// Return true if the controller has been opened and currently
     /// connected.
+    #[doc(alias = "SDL_GameControllerGetAttached")]
     pub fn attached(&self) -> bool {
         unsafe { sys::SDL_GameControllerGetAttached(self.raw) != sys::SDL_bool::SDL_FALSE }
     }
 
     /// Return the joystick instance id of this controller
+    #[doc(alias = "SDL_GameControllerGetJoystick")]
     pub fn instance_id(&self) -> u32 {
         let result = unsafe {
           let joystick = sys::SDL_GameControllerGetJoystick(self.raw);
@@ -378,6 +396,7 @@ impl GameController {
     }
 
     /// Get the position of the given `axis`
+    #[doc(alias = "SDL_GameControllerGetAxis")]
     pub fn axis(&self, axis: Axis) -> i16 {
         // This interface is a bit messed up: 0 is a valid position
         // but can also mean that an error occured.
@@ -391,6 +410,7 @@ impl GameController {
     }
 
     /// Returns `true` if `button` is pressed.
+    #[doc(alias = "SDL_GameControllerGetButton")]
     pub fn button(&self, button: Button) -> bool {
         // This interface is a bit messed up: 0 is a valid position
         // but can also mean that an error occured.
@@ -414,6 +434,7 @@ impl GameController {
     /// the rumble effect to keep playing for a long time, as this results in
     /// the effect ending immediately after starting due to an overflow.
     /// Use some smaller, "huge enough" number instead.
+    #[doc(alias = "SDL_GameControllerRumble")]
     pub fn set_rumble(&mut self,
                       low_frequency_rumble: u16,
                       high_frequency_rumble: u16,
@@ -436,6 +457,7 @@ impl GameController {
 }
 
 impl Drop for GameController {
+    #[doc(alias = "SDL_GameControllerClose")]
     fn drop(&mut self) {
         unsafe { sys::SDL_GameControllerClose(self.raw) }
     }