Fix inconsistencies in documentation/attributes/function inclusion (#177)

* Apply documentation to audio methods

* Make getter methods const

* Apply documentation to automation methods

* Apply documentation to `camera.rs`

* Apply documentation to `color.rs`

* Add color palette impls

* Fix documentation comment

* Apply documentation to `drawing.rs

* Fix inconsistent name pattern

* Fix documentation and inline inconsistencies in `file.rs`

* Add missing inlines in `input.rs`

* Improve consistency within `math.rs`

* Add missing documentation to `models.rs`

* Improve API consistency in `shaders.rs`

* Add missing documentation to `text.rs`

* Add optional attributes to `make_thin_wrapper!`

* Add documentation to `texture.rs`

* Add missing docs to `vr.rs`

* Add missing documentation to `window.rs`

* Confirm all public functions from Raylib API are documented

* Add documentation comments to thin wrappers in `audio.rs`

Author: AmityWilder

raylib/src/core/audio.rs

@@ -6,11 +6,31 @@ use std::ffi::CString;
 use std::marker::PhantomData;
 use std::path::Path;
 
-make_thin_wrapper_lifetime!(Wave, ffi::Wave, RaylibAudio, ffi::UnloadWave);
+make_thin_wrapper_lifetime!(
+    /// Wave, audio wave data
+    Wave,
+    ffi::Wave,
+    RaylibAudio,
+    ffi::UnloadWave
+);
 
-make_thin_wrapper_lifetime!(Sound, ffi::Sound, RaylibAudio, (ffi::UnloadSound), true);
-make_thin_wrapper_lifetime!(Music, ffi::Music, RaylibAudio, ffi::UnloadMusicStream);
 make_thin_wrapper_lifetime!(
+    /// Sound
+    Sound,
+    ffi::Sound,
+    RaylibAudio,
+    (ffi::UnloadSound),
+    true
+);
+make_thin_wrapper_lifetime!(
+    /// Music, audio stream, anything longer than ~10 seconds should be streamed
+    Music,
+    ffi::Music,
+    RaylibAudio,
+    ffi::UnloadMusicStream
+);
+make_thin_wrapper_lifetime!(
+    /// AudioStream, custom audio stream
     AudioStream,
     ffi::AudioStream,
     RaylibAudio,
@@ -87,14 +107,14 @@ impl RaylibAudio {
     pub fn set_master_volume(&self, volume: f32) {
         unsafe { ffi::SetMasterVolume(volume) }
     }
-    
+
     /// Sets default audio buffer size for new audio streams.
     #[inline]
     pub fn set_audio_stream_buffer_size_default(&self, size: i32) {
         unsafe {
             ffi::SetAudioStreamBufferSizeDefault(size);
         }
-    }    
+    }
 
     /// Loads a new sound from file.
     #[inline]
@@ -199,16 +219,24 @@ impl<'aud> Drop for RaylibAudio {
 }
 
 impl<'aud> Wave<'aud> {
-    pub fn frame_count(&self) -> u32 {
+    /// Total number of frames (considering channels)
+    #[inline]
+    pub const fn frame_count(&self) -> u32 {
         self.0.frameCount
     }
-    pub fn sample_rate(&self) -> u32 {
+    /// Frequency (samples per second)
+    #[inline]
+    pub const fn sample_rate(&self) -> u32 {
         self.0.sampleRate
     }
-    pub fn sample_size(&self) -> u32 {
+    /// Bit depth (bits per sample): 8, 16, 32 (24 not supported)
+    #[inline]
+    pub const fn sample_size(&self) -> u32 {
         self.0.sampleSize
     }
-    pub fn channels(&self) -> u32 {
+    /// Number of channels (1-mono, 2-stereo, ...)
+    #[inline]
+    pub const fn channels(&self) -> u32 {
         self.0.channels
     }
     pub unsafe fn inner(self) -> ffi::Wave {
@@ -217,6 +245,7 @@ impl<'aud> Wave<'aud> {
         inner
     }
 
+    /// Checks if wave data is valid (data loaded and parameters)
     #[inline]
     pub fn is_wave_valid(&self) -> bool {
         unsafe { ffi::IsWaveValid(self.0) }
@@ -229,8 +258,8 @@ impl<'aud> Wave<'aud> {
         unsafe { ffi::ExportWave(self.0, c_filename.as_ptr()) }
     }
 
-    /// Export wave sample data to code (.h)
-    /*#[inline]
+    /*/// Export wave sample data to code (.h)
+    #[inline]
     pub fn export_wave_as_code(&self, filename: &str) -> bool {
         let c_filename = CString::new(filename).unwrap();
         unsafe { ffi::ExportWaveAsCode(self.0, c_filename.as_ptr()) }
@@ -279,11 +308,15 @@ impl<'aud> AsMut<ffi::AudioStream> for Sound<'aud> {
 }
 
 impl<'aud> Sound<'aud> {
+    /// Checks if a sound is valid (data loaded and buffers initialized)
+    #[inline]
     pub fn is_sound_valid(&self) -> bool {
         unsafe { ffi::IsSoundValid(self.0) }
     }
 
-    pub fn frame_count(&self) -> u32 {
+    /// Total number of frames (considering channels)
+    #[inline]
+    pub const fn frame_count(&self) -> u32 {
         self.0.frameCount
     }
     pub unsafe fn inner(self) -> ffi::Sound {
@@ -334,6 +367,7 @@ impl<'aud> Sound<'aud> {
         unsafe { ffi::SetSoundPitch(self.0, pitch) }
     }
 
+    /// Set pan for a sound (0.5 is center)
     #[inline]
     pub fn set_pan(&self, pan: f32) {
         unsafe { ffi::SetSoundPan(self.0, pan) }
@@ -354,11 +388,15 @@ impl<'aud> Sound<'aud> {
 }
 
 impl<'aud, 'bind> SoundAlias<'aud, 'bind> {
+    /// Checks if a sound is valid (data loaded and buffers initialized)
+    #[inline]
     pub fn is_sound_valid(&self) -> bool {
         unsafe { ffi::IsSoundValid(self.0) }
     }
 
-    pub fn frame_count(&self) -> u32 {
+    /// Total number of frames (considering channels)
+    #[inline]
+    pub const fn frame_count(&self) -> u32 {
         self.0.frameCount
     }
     pub unsafe fn inner(self) -> ffi::Sound {
@@ -409,6 +447,7 @@ impl<'aud, 'bind> SoundAlias<'aud, 'bind> {
         unsafe { ffi::SetSoundPitch(self.0, pitch) }
     }
 
+    /// Set pan for a sound (0.5 is center)
     #[inline]
     pub fn set_pan(&self, pan: f32) {
         unsafe { ffi::SetSoundPan(self.0, pan) }
@@ -482,33 +521,44 @@ impl<'aud> Music<'aud> {
         unsafe { ffi::GetMusicTimePlayed(self.0) }
     }
 
+    /// Seek music to a position (in seconds)
     #[inline]
     pub fn seek_stream(&self, position: f32) {
         unsafe { ffi::SeekMusicStream(self.0, position) }
     }
 
+    /// Set pan for a music (0.5 is center)
     #[inline]
     pub fn set_pan(&self, pan: f32) {
         unsafe { ffi::SetMusicPan(self.0, pan) }
     }
 
+    /// Checks if a music stream is valid (context and buffers initialized)
     #[inline]
     pub fn is_music_valid(&self) -> bool {
         unsafe { ffi::IsMusicValid(self.0) }
     }
 }
 
 impl<'aud> AudioStream<'aud> {
+    /// Checks if an audio stream is valid (buffers initialized)
+    #[inline]
     pub fn is_audio_stream_valid(&self) -> bool {
         unsafe { ffi::IsAudioStreamValid(self.0) }
     }
-    pub fn sample_rate(&self) -> u32 {
+    /// Frequency (samples per second)
+    #[inline]
+    pub const fn sample_rate(&self) -> u32 {
         self.0.sampleRate
     }
-    pub fn sample_size(&self) -> u32 {
+    /// Bit depth (bits per sample): 8, 16, 32 (24 not supported)
+    #[inline]
+    pub const fn sample_size(&self) -> u32 {
         self.0.sampleSize
     }
-    pub fn channels(&self) -> u32 {
+    /// Number of channels (1-mono, 2-stereo, ...)
+    #[inline]
+    pub const fn channels(&self) -> u32 {
         self.0.channels
     }
 
@@ -590,6 +640,8 @@ impl<'aud> AudioStream<'aud> {
         unsafe { ffi::IsAudioStreamProcessed(self.0) }
     }
 
+    /// Set pan for audio stream (0.5 is centered)
+    #[inline]
     pub fn set_pan(&self, pan: f32) {
         unsafe {
             ffi::SetAudioStreamPan(self.0, pan);
@@ -598,6 +650,8 @@ impl<'aud> AudioStream<'aud> {
 }
 
 impl<'bind> Sound<'_> {
+    /// Clone sound from existing sound data, clone does not own wave data
+    // NOTE: Wave data must be unallocated manually and will be shared across all clones
     pub fn alias<'snd>(&'snd self) -> Result<SoundAlias<'bind, 'snd>, Error> {
         let s = unsafe { ffi::LoadSoundAlias(self.0) };
         if s.stream.buffer.is_null() {

raylib/src/core/automation.rs

@@ -73,10 +73,12 @@ make_thin_wrapper!(
 
 impl AutomationEventList {
     /// Length of the automation event list
+    #[inline]
     pub const fn count(&self) -> u32 {
         self.0.count
     }
     /// The amount of automation events that can be held in this list.
+    #[inline]
     pub const fn capacity(&self) -> u32 {
         self.0.capacity
     }
@@ -108,18 +110,26 @@ make_thin_wrapper!(
 );
 
 impl AutomationEvent {
+    /// Event frame
+    #[inline]
     pub const fn frame(&self) -> u32 {
         self.0.frame
     }
+    /// Event type (AutomationEventType)
+    #[inline]
     pub const fn get_type(&self) -> u32 {
         self.0.type_
     }
+    /// Event parameters (if required)
+    #[inline]
     pub const fn params(&self) -> [i32; 4] {
         self.0.params
     }
 }
 
 impl AutomationEvent {
+    /// Play a recorded automation event
+    #[inline]
     pub fn play(&self) {
         unsafe { ffi::PlayAutomationEvent(self.0) }
     }
@@ -130,6 +140,7 @@ fn unload_automation_event(_s: ffi::AutomationEvent) {
 }
 
 impl RaylibHandle {
+    /// Load automation events list from file, NULL for empty list, capacity = MAX_AUTOMATION_EVENTS
     pub fn load_automation_event_list(&self, file_name: Option<PathBuf>) -> AutomationEventList {
         match file_name {
             Some(a) => {
@@ -139,17 +150,25 @@ impl RaylibHandle {
             None => AutomationEventList(unsafe { ffi::LoadAutomationEventList(null()) }),
         }
     }
+    /// Set automation event list to record to
+    #[inline]
     pub fn set_automation_event_list(&self, l: &mut AutomationEventList) {
         unsafe {
             ffi::SetAutomationEventList(&mut l.0 as *mut ffi::AutomationEventList);
         }
     }
+    /// Set automation event internal base frame to start recording
+    #[inline]
     pub fn set_automation_event_base_frame(&self, b: i32) {
         unsafe { ffi::SetAutomationEventBaseFrame(b) };
     }
+    /// Start recording automation events (AutomationEventList must be set)
+    #[inline]
     pub fn start_automation_event_recording(&self) {
         unsafe { ffi::StartAutomationEventRecording() };
     }
+    /// Stop recording automation events
+    #[inline]
     pub fn stop_automation_event_recording(&self) {
         unsafe { ffi::StopAutomationEventRecording() };
     }

raylib/src/core/camera.rs

@@ -5,15 +5,22 @@ use crate::core::math::{Vector2, Vector3};
 use crate::core::RaylibHandle;
 use crate::ffi;
 
+/// Camera, defines position/orientation in 3d space
 #[repr(C)]
 #[derive(Debug, Copy, Clone)]
 pub struct Camera3D {
+    /// Camera position
     pub position: Vector3,
+    /// Camera target it looks-at
     pub target: Vector3,
+    /// Camera up vector (rotation over its axis)
     pub up: Vector3,
+    /// Camera field-of-view aperture in Y (degrees) in perspective, used as near plane width in orthographic
     pub fovy: f32,
+    /// Camera projection: CAMERA_PERSPECTIVE or CAMERA_ORTHOGRAPHIC
     projection_: ffi::CameraProjection,
 }
+/// Camera type fallback, defaults to Camera3D
 pub type Camera = Camera3D;
 
 impl From<ffi::Camera3D> for Camera3D {
@@ -40,12 +47,17 @@ impl Into<ffi::Camera3D> for &Camera3D {
     }
 }
 
+/// Camera2D, defines position/orientation in 2d space
 #[repr(C)]
 #[derive(Debug, Copy, Clone, Default)]
 pub struct Camera2D {
+    /// Camera offset (displacement from target)
     pub offset: Vector2,
+    /// Camera target (rotation and zoom origin)
     pub target: Vector2,
+    /// Camera rotation in degrees
     pub rotation: f32,
+    /// Camera zoom (scaling), should be 1.0 by default
     pub zoom: f32,
 }
 
@@ -73,8 +85,9 @@ impl Into<ffi::Camera2D> for &Camera2D {
 }
 
 impl Camera3D {
-    pub fn camera_type(&self) -> crate::consts::CameraProjection {
-        unsafe { std::mem::transmute(self.projection_.clone()) }
+    /// Camera projection: CAMERA_PERSPECTIVE or CAMERA_ORTHOGRAPHIC
+    pub const fn camera_type(&self) -> crate::consts::CameraProjection {
+        unsafe { std::mem::transmute_copy(&self.projection_) }
     }
     /// Create a perspective camera.
     /// fovy is in degrees
@@ -106,7 +119,8 @@ impl RaylibHandle {
             *camera = fficam.into();
         }
     }
-    
+
+    /// Update camera movement/rotation
     pub fn update_camera_pro(&self, camera: &mut Camera3D, movement: Vector3, rotation: Vector3, zoom: f32) {
         unsafe {
             let mut fficam: ffi::Camera3D = (*camera).into();