asio sys lib comments and rust fmt

asio-sys/src/lib.rs

@@ -11,57 +11,85 @@ mod asio_import;
 #[macro_use]
 pub mod errors;
 
-use errors::{AsioError, AsioDriverError, AsioErrorWrapper};
+use errors::{AsioDriverError, AsioError, AsioErrorWrapper};
 use std::ffi::CStr;
 use std::ffi::CString;
 use std::mem;
 use std::os::raw::{c_char, c_double, c_long, c_void};
-use std::sync::atomic::{AtomicUsize, AtomicBool, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
 use std::sync::{Mutex, MutexGuard};
 
+// Bindings import
 use asio_import as ai;
 
-
+// TODO I dont think this is needed anymore
 pub struct CbArgs<S, D> {
     pub stream_id: S,
     pub data: D,
 }
 
+/// Holds the pointer to the callbacks that come from cpal
 struct BufferCallback(Box<FnMut(i32) + Send>);
 
+/// A global way to access all the callbacks.
+/// This is required because of how ASIO
+/// calls the buffer_switch function.
+/// Options are used so that when a callback is
+/// removed we don't change the Vec indicies.
+/// The indicies are how we match a callback
+/// with a stream.
 lazy_static! {
     static ref buffer_callback: Mutex<Vec<Option<BufferCallback>>> = Mutex::new(Vec::new());
 }
 
+/// Globally available state of the ASIO driver.
+/// This allows all calls the the driver to ensure 
+/// they are calling in the correct state.
+/// It also prevents multiple calls happening at once.
 lazy_static! {
-    static ref ASIO_DRIVERS: Mutex<AsioWrapper> = Mutex::new(AsioWrapper{
+    static ref ASIO_DRIVERS: Mutex<AsioWrapper> = Mutex::new(AsioWrapper {
         state: AsioState::Offline,
     });
 }
 
+/// Count of active device and streams.
+/// Used to clean up the driver connection 
+/// when there are no active connections.
 static STREAM_DRIVER_COUNT: AtomicUsize = AtomicUsize::new(0);
+/// Tracks which buffer needs to be silenced.
 pub static SILENCE_FIRST: AtomicBool = AtomicBool::new(false);
 pub static SILENCE_SECOND: AtomicBool = AtomicBool::new(false);
 
+/// Amount of input and output 
+/// channels available.
 #[derive(Debug)]
 pub struct Channel {
     pub ins: i64,
     pub outs: i64,
 }
 
+/// Sample rate of the ASIO device.
 #[derive(Debug)]
 pub struct SampleRate {
     pub rate: u32,
 }
 
+/// A marker type to make sure
+/// all calls to the driver have an
+/// active connection.
 #[derive(Debug, Clone)]
 pub struct Drivers;
 
+/// Tracks the current state of the 
+/// ASIO drivers.
 #[derive(Debug)]
 struct AsioWrapper {
     state: AsioState,
 }
 
+/// All possible states of the 
+/// ASIO driver. Mapped to the 
+/// FSM in the ASIO SDK docs.
 #[derive(Debug)]
 enum AsioState {
     Offline,
@@ -71,18 +99,27 @@ enum AsioState {
     Running,
 }
 
+/// Input and Output streams.
+/// There is only ever max one
+/// input and one output. Only one
+/// is required.
 pub struct AsioStreams {
     pub input: Option<AsioStream>,
     pub output: Option<AsioStream>,
 }
 
+/// A stream to ASIO.
+/// Contains the buffers.
 pub struct AsioStream {
+    /// A Double buffer per channel
     pub buffer_infos: Vec<AsioBufferInfo>,
+    /// Size of each buffer
     pub buffer_size: i32,
 }
 
-// This is a direct copy of the ASIOSampleType
-// inside ASIO SDK.
+/// All the possible types from ASIO.
+/// This is a direct copy of the ASIOSampleType
+/// inside ASIO SDK. 
 #[derive(Debug, FromPrimitive)]
 #[repr(C)]
 pub enum AsioSampleType {
@@ -120,14 +157,20 @@ pub enum AsioSampleType {
     ASIOSTLastEntry,
 }
 
+/// Gives information about buffers
+/// Receives pointers to buffers
 #[derive(Debug, Copy, Clone)]
 #[repr(C)]
 pub struct AsioBufferInfo {
+    /// 0 for output 1 for input
     pub is_input: c_long,
+    /// Which channel. Starts at 0
     pub channel_num: c_long,
+    /// Pointer to each half of the double buffer.
     pub buffers: [*mut c_void; 2],
 }
 
+/// Callbacks that ASIO calls
 #[repr(C)]
 struct AsioCallbacks {
     buffer_switch: extern "C" fn(double_buffer_index: c_long, direct_process: c_long) -> (),
@@ -141,7 +184,14 @@ struct AsioCallbacks {
         direct_process: c_long,
     ) -> *mut ai::ASIOTime,
 }
+
+/// This is called by ASIO.
+/// Here we run the callback for each stream.
+/// double_buffer_index is either 0 or 1
+/// indicating which buffer to fill
 extern "C" fn buffer_switch(double_buffer_index: c_long, _direct_process: c_long) -> () {
+    // This lock is probably unavoidable 
+    // but locks in the audio stream is not great
     let mut bcs = buffer_callback.lock().unwrap();
 
     for mut bc in bcs.iter_mut() {
@@ -151,48 +201,61 @@ extern "C" fn buffer_switch(double_buffer_index: c_long, _direct_process: c_long
     }
 }
 
+/// Idicates the sample rate has changed
+/// TODO Change the sample rate when this
+/// is called.
 extern "C" fn sample_rate_did_change(_s_rate: c_double) -> () {}
 
+/// Messages for ASIO
+/// This is not currently used
 extern "C" fn asio_message(
     _selector: c_long, _value: c_long, _message: *mut (), _opt: *mut c_double,
 ) -> c_long {
+    // TODO Impliment this to give proper responses
     4 as c_long
 }
 
+/// Similar to buffer switch but with time info
+/// Not currently used
 extern "C" fn buffer_switch_time_info(
     params: *mut ai::ASIOTime, _double_buffer_index: c_long, _direct_process: c_long,
 ) -> *mut ai::ASIOTime {
     params
 }
 
+/// Helper function for getting the drivers.
+/// Note this is a lock.
 fn get_drivers() -> MutexGuard<'static, AsioWrapper> {
     ASIO_DRIVERS.lock().unwrap()
 }
 
 impl Drivers {
+    /// Load the drivers from a driver name.
+    /// This will destroy the old drivers.
     #[allow(unused_assignments)]
     pub fn load(driver_name: &str) -> Result<Self, AsioDriverError> {
         let mut drivers = get_drivers();
         // Make owned CString to send to load driver
-        let mut my_driver_name =
-            CString::new(driver_name).expect("Can't go from str to CString");
+        let mut my_driver_name = CString::new(driver_name).expect("Can't go from str to CString");
         let raw = my_driver_name.into_raw();
         let mut driver_info = ai::ASIODriverInfo {
             _bindgen_opaque_blob: [0u32; 43],
         };
         unsafe {
+            // Destroy old drivers and load new drivers.
             let load_result = drivers.load(raw);
             // Take back ownership
             my_driver_name = CString::from_raw(raw);
             if load_result {
+                // Initialize ASIO
                 match drivers.asio_init(&mut driver_info) {
                     Ok(_) => {
+                        // If it worked then add a active connection to the drivers
+                        // TODO Make sure this is decremented when old drivers are dropped
                         STREAM_DRIVER_COUNT.fetch_add(1, Ordering::SeqCst);
                         Ok(Drivers)
                     },
-                    Err(_) => {
-                        Err(AsioDriverError::DriverLoadError)
-                    },
+                    Err(_) => Err(AsioDriverError::DriverLoadError),
                 }
             } else {
                 Err(AsioDriverError::DriverLoadError)
@@ -200,13 +263,8 @@ impl Drivers {
         }
     }
 
-    /// Returns the channels for the driver it's passed
-    ///
-    /// # Arguments
-    /// * `driver name` - Name of the driver
-    /// # Usage
-    /// Use the get_driver_list() to get the list of names
-    /// Then pass the one you want to get_channels
+    /// Returns the number of input and output 
+    /// channels for the active drivers
     pub fn get_channels(&self) -> Channel {
         let channel: Channel;
 
@@ -214,7 +272,11 @@ impl Drivers {
         let mut ins: c_long = 0;
         let mut outs: c_long = 0;
         unsafe {
-            get_drivers().asio_get_channels(&mut ins, &mut outs).expect("failed to get channels");
+            get_drivers()
+                .asio_get_channels(&mut ins, &mut outs)
+                // TODO pass this result along
+                // and handle it without panic
+                .expect("failed to get channels");
             channel = Channel {
                 ins: ins as i64,
                 outs: outs as i64,
@@ -224,6 +286,7 @@ impl Drivers {
         channel
     }
 
+    /// Get current sample rate of the active drivers
     pub fn get_sample_rate(&self) -> SampleRate {
         let sample_rate: SampleRate;
 
@@ -231,47 +294,59 @@ impl Drivers {
         let mut rate: c_double = 0.0f64;
 
         unsafe {
-            get_drivers().asio_get_sample_rate(&mut rate).expect("failed to get sample rate");
+            get_drivers()
+                .asio_get_sample_rate(&mut rate)
+                // TODO pass this result along
+                // and handle it without panic
+                .expect("failed to get sample rate");
             sample_rate = SampleRate { rate: rate as u32 };
         }
 
         sample_rate
     }
 
-    pub fn set_sample_rate(&self, sample_rate: u32) -> Result<(), AsioError>{
+    /// Set the sample rate for the active drivers
+    pub fn set_sample_rate(&self, sample_rate: u32) -> Result<(), AsioError> {
         // Initialize memory for calls
         let rate: c_double = c_double::from(sample_rate);
 
-        unsafe {
-            get_drivers().asio_set_sample_rate(rate)
-        }
+        unsafe { get_drivers().asio_set_sample_rate(rate) }
     }
 
+    /// Can the drivers accept the given sample rate
     pub fn can_sample_rate(&self, sample_rate: u32) -> bool {
         // Initialize memory for calls
         let rate: c_double = c_double::from(sample_rate);
 
-        unsafe {
-            get_drivers().asio_can_sample_rate(rate).is_ok()
-        }
+        // TODO this gives an error is it can't handle the sample
+        // rate but it can also give error for no divers
+        // Both should be handled.
+        unsafe { get_drivers().asio_can_sample_rate(rate).is_ok() }
     }
 
+    /// Get the current data type of the active drivers.
+    /// Just queries a single channels type as all channels
+    /// have the same sample type.
     pub fn get_data_type(&self) -> Result<AsioSampleType, AsioDriverError> {
+        // TODO make this a seperate call for input and output as
+        // it is possible that input and output have different sample types
         // Initialize memory for calls
         let mut channel_info = ai::ASIOChannelInfo {
+            // Which channel we are querying
             channel: 0,
+            // Was it input or output
             isInput: 0,
+            // Was it active
             isActive: 0,
             channelGroup: 0,
+            // The sample type
             type_: 0,
             name: [0 as c_char; 32],
         };
         unsafe {
             match get_drivers().asio_get_channel_info(&mut channel_info) {
-                Ok(_) => {
-                    num::FromPrimitive::from_i32(channel_info.type_)
-                        .map_or(Err(AsioDriverError::TypeError), |t| Ok(t))
-                },
+                Ok(_) => num::FromPrimitive::from_i32(channel_info.type_)
+                    .map_or(Err(AsioDriverError::TypeError), |t| Ok(t)),
                 Err(e) => {
                     println!("Error getting data type {}", e);
                     Err(AsioDriverError::DriverLoadError)
@@ -280,69 +355,112 @@ impl Drivers {
         }
     }
 
-    pub fn prepare_input_stream(&self, output: Option<AsioStream>, num_channels: usize) -> Result<AsioStreams, AsioDriverError> {
-        let buffer_infos = (0..num_channels)
-            .map(|i| {
-                AsioBufferInfo {
+    /// Prepare the input stream.
+    /// Because only the latest call
+    /// to ASIOCreateBuffers is relevant this
+    /// call will destroy all past active buffers
+    /// and recreate them. For this reason we take 
+    /// the output stream if it exists.
+    /// num_channels is the number of input channels.
+    /// This returns a full AsioStreams with both input
+    /// and output if output was active.
+    pub fn prepare_input_stream(
+        &self, output: Option<AsioStream>, num_channels: usize,
+    ) -> Result<AsioStreams, AsioDriverError> {
+        let buffer_infos = (0 .. num_channels)
+            .map(|i| AsioBufferInfo {
+                // These are output channels
                 is_input: 1,
+                // Channel index
                 channel_num: i as c_long,
+                // Double buffer. We don't know the type
+                // at this point
                 buffers: [std::ptr::null_mut(); 2],
-                }
-            })
-            .collect();
+            }).collect();
 
-        let streams = AsioStreams{input: Some(AsioStream{buffer_infos, buffer_size: 0}), output};
-        self.create_streams(streams)
-    }
-
-    /// Creates the output stream
-    pub fn prepare_output_stream(&self, input: Option<AsioStream>, num_channels: usize) -> Result<AsioStreams, AsioDriverError> {
-        // Initialize data for FFI
-        let buffer_infos = (0..num_channels)
-            .map(|i| {
-                AsioBufferInfo {
-                    is_input: 0,
-                    channel_num: i as c_long,
-                    buffers: [std::ptr::null_mut(); 2],
-                }
-            })
-            .collect();
-        let streams = AsioStreams{output: Some(AsioStream{buffer_infos, buffer_size: 0}), input};
-        self.create_streams(streams)
-    }
-
-    /// Creates the output stream
-    fn create_streams(&self, streams: AsioStreams) -> Result<AsioStreams, AsioDriverError> {
-        let AsioStreams {
-            input,
+        // Create the streams
+        let streams = AsioStreams {
+            input: Some(AsioStream {
+                buffer_infos,
+                buffer_size: 0,
+            }),
             output,
-        } = streams;
+        };
+        self.create_streams(streams)
+    }
+
+    /// Prepare the output stream.
+    /// Because only the latest call
+    /// to ASIOCreateBuffers is relevant this
+    /// call will destroy all past active buffers
+    /// and recreate them. For this reason we take 
+    /// the input stream if it exists.
+    /// num_channels is the number of output channels.
+    /// This returns a full AsioStreams with both input
+    /// and output if input was active.
+    pub fn prepare_output_stream(
+        &self, input: Option<AsioStream>, num_channels: usize,
+    ) -> Result<AsioStreams, AsioDriverError> {
+        // Initialize data for FFI
+        let buffer_infos = (0 .. num_channels)
+            .map(|i| AsioBufferInfo {
+                // These are outputs
+                is_input: 0,
+                // Channel index
+                channel_num: i as c_long,
+                // Pointer to each buffer. We don't know
+                // the type yet.
+                buffers: [std::ptr::null_mut(); 2],
+            }).collect();
+
+        // Create streams
+        let streams = AsioStreams {
+            output: Some(AsioStream {
+                buffer_infos,
+                buffer_size: 0,
+            }),
+            input,
+        };
+        self.create_streams(streams)
+    }
+
+    /// Creates the streams.
+    /// Both input and output streams
+    /// need to be created together as
+    /// a single slice of ASIOBufferInfo
+    fn create_streams(&self, streams: AsioStreams) -> Result<AsioStreams, AsioDriverError> {
+        let AsioStreams { input, output } = streams;
         match (input, output) {
+            // Both stream exist.
             (Some(input), Some(mut output)) => {
                 let split_point = input.buffer_infos.len();
                 let mut bi = input.buffer_infos;
+                // Append the output to the input channels
                 bi.append(&mut output.buffer_infos);
-                self.create_buffers(bi)
-                    .map(|(mut bi, buffer_size)|{
+                // Create the buffers.
+                // if successful then split the output
+                // and input again
+                self.create_buffers(bi).map(|(mut bi, buffer_size)| {
                     let out_bi = bi.split_off(split_point);
                     let in_bi = bi;
-                        let output = Some(AsioStream{
+                    let output = Some(AsioStream {
                         buffer_infos: out_bi,
                         buffer_size,
                     });
-                        let input = Some(AsioStream{
+                    let input = Some(AsioStream {
                         buffer_infos: in_bi,
                         buffer_size,
                     });
-                        AsioStreams{output, input}
+                    AsioStreams { output, input }
                 })
             },
+            // Just input
             (Some(input), None) => {
                 self.create_buffers(input.buffer_infos)
                     .map(|(buffer_infos, buffer_size)| {
                         STREAM_DRIVER_COUNT.fetch_add(1, Ordering::SeqCst);
-                        AsioStreams{
-                            input: Some(AsioStream{
+                        AsioStreams {
+                            input: Some(AsioStream {
                                 buffer_infos,
                                 buffer_size,
                             }),
@@ -350,12 +468,13 @@ impl Drivers {
                         }
                     })
             },
+            // Just output
             (None, Some(output)) => {
                 self.create_buffers(output.buffer_infos)
                     .map(|(buffer_infos, buffer_size)| {
                         STREAM_DRIVER_COUNT.fetch_add(1, Ordering::SeqCst);
-                        AsioStreams{
-                            output: Some(AsioStream{
+                        AsioStreams {
+                            output: Some(AsioStream {
                                 buffer_infos,
                                 buffer_size,
                             }),
@@ -363,13 +482,19 @@ impl Drivers {
                         }
                     })
             },
+            // Impossible
             (None, None) => panic!("Trying to create streams without preparing"),
         }
-
     }
 
-    fn create_buffers(&self, buffer_infos: Vec<AsioBufferInfo>) 
-    -> Result<(Vec<AsioBufferInfo>, c_long), AsioDriverError>{
+    /// Ask ASIO to allocate the buffers
+    /// and give the callback pointers.
+    /// This will destroy any already allocated 
+    /// buffers.
+    /// The prefered buffer size from ASIO is used.
+    fn create_buffers(
+        &self, buffer_infos: Vec<AsioBufferInfo>,
+    ) -> Result<(Vec<AsioBufferInfo>, c_long), AsioDriverError> {
         let num_channels = buffer_infos.len();
         let callbacks = AsioCallbacks {
             buffer_switch: buffer_switch,
@@ -391,48 +516,46 @@ impl Drivers {
             // max possible size
             // preferred size
             // granularity
-            drivers.asio_get_buffer_size(
+            drivers
+                .asio_get_buffer_size(
                     &mut min_b_size,
                     &mut max_b_size,
                     &mut pref_b_size,
                     &mut grans,
                 ).expect("Failed getting buffers");
             if pref_b_size > 0 {
-                /*
-                let mut buffer_info_convert: Vec<ai::ASIOBufferInfo> = buffer_infos
-                    .into_iter()
-                    .map(|bi| mem::transmute::<AsioBufferInfo, ai::ASIOBufferInfo>(bi))
-                    .collect();
-                    */
-                let mut buffer_info_convert = mem::transmute::<Vec<AsioBufferInfo>, Vec<ai::ASIOBufferInfo>>(buffer_infos);
+                // Convert Rust structs to opaque ASIO structs
+                let mut buffer_info_convert =
+                    mem::transmute::<Vec<AsioBufferInfo>, Vec<ai::ASIOBufferInfo>>(buffer_infos);
                 let mut callbacks_convert =
                     mem::transmute::<AsioCallbacks, ai::ASIOCallbacks>(callbacks);
-                drivers.asio_create_buffers(
+                drivers
+                    .asio_create_buffers(
                         buffer_info_convert.as_mut_ptr(),
                         num_channels as i32,
                         pref_b_size,
                         &mut callbacks_convert,
-                ).map(|_|{
-                    let buffer_infos = mem::transmute::<Vec<ai::ASIOBufferInfo>, Vec<AsioBufferInfo>>(buffer_info_convert);
-                    for d in &buffer_infos {
-                        println!("after {:?}", d);
-                    }
-                    println!("channels: {:?}", num_channels);
-
+                    ).map(|_| {
+                        let buffer_infos = mem::transmute::<
+                            Vec<ai::ASIOBufferInfo>,
+                            Vec<AsioBufferInfo>,
+                        >(buffer_info_convert);
                         (buffer_infos, pref_b_size)
-                }).map_err(|e|{
+                    }).map_err(|e| {
                         AsioDriverError::BufferError(format!(
-                    "failed to create buffers, error code: {:?}", e))
+                            "failed to create buffers, error code: {:?}",
+                            e
+                        ))
                     })
             } else {
-                Err(AsioDriverError::BufferError(
-                    "bad buffer size".to_owned(),
-                ))
+                Err(AsioDriverError::BufferError("bad buffer size".to_owned()))
             }
         }
     }
 }
 
+/// If all drivers and streams are gone
+/// clean up drivers
 impl Drop for Drivers {
     fn drop(&mut self) {
         let count = STREAM_DRIVER_COUNT.fetch_sub(1, Ordering::SeqCst);
@@ -442,17 +565,21 @@ impl Drop for Drivers {
     }
 }
 
+/// Required for Mutex
 unsafe impl Send for AsioWrapper {}
+/// Required for Mutex
+unsafe impl Send for AsioStream {}
 
 impl BufferCallback {
+    /// Calls the inner callback
     fn run(&mut self, index: i32) {
         let cb = &mut self.0;
         cb(index);
     }
 }
 
-unsafe impl Send for AsioStream {}
 
+/// Adds a callback to the list of active callbacks
 pub fn set_callback<F: 'static>(callback: F) -> ()
 where
     F: FnMut(i32) + Send,
@@ -461,56 +588,78 @@ where
     bc.push(Some(BufferCallback(Box::new(callback))));
 }
 
-/// Returns a list of all the ASIO drivers
+/// Returns a list of all the ASIO devices.
+/// This is used at the start to allow the
+/// user to choose which device they want.
 #[allow(unused_assignments)]
 pub fn get_driver_list() -> Vec<String> {
+    // The most devices we can take
     const MAX_DRIVERS: usize = 100;
+    // Max length for divers name
     const CHAR_LEN: usize = 32;
 
+    // 2D array of driver names set to 0
     let mut driver_names: [[c_char; CHAR_LEN]; MAX_DRIVERS] = [[0; CHAR_LEN]; MAX_DRIVERS];
+    // Pointer to each driver name
     let mut p_driver_name: [*mut i8; MAX_DRIVERS] = [0 as *mut i8; MAX_DRIVERS];
 
     for i in 0 .. MAX_DRIVERS {
         p_driver_name[i] = driver_names[i].as_mut_ptr();
     }
 
-
     unsafe {
         let num_drivers = ai::get_driver_names(p_driver_name.as_mut_ptr(), MAX_DRIVERS as i32);
 
-        (0..num_drivers)
-            .map(|i|{
+        (0 .. num_drivers)
+            .map(|i| {
                 let mut my_driver_name = CString::new("").unwrap();
                 let name = CStr::from_ptr(p_driver_name[i as usize]);
                 my_driver_name = name.to_owned();
-                my_driver_name.into_string().expect("Failed to convert driver name")
-            })
-            .collect()
+                my_driver_name
+                    .into_string()
+                    .expect("Failed to convert driver name")
+            }).collect()
     }
 }
 
+/// Cleans up the drivers and
+/// any allocations
 pub fn clean_up() {
     let mut drivers = get_drivers();
     drivers.clean_up();
 }
 
+/// Starts input and output streams playing
 pub fn play() {
     unsafe {
+        // TODO handle result instead of printing
         let result = get_drivers().asio_start();
         println!("start result: {:?}", result);
     }
 }
 
+/// Stops input and output streams playing
 pub fn stop() {
     unsafe {
+        // TODO handle result instead of printing
         let result = get_drivers().asio_stop();
         println!("stop result: {:?}", result);
     }
 }
 
+/// All the actual calls to ASIO.
+/// This is where we handle the state
+/// and assert that all calls
+/// happen in the correct state.
+/// TODO it is possible to enforce most of this
+/// at compile time using type parameters.
+/// All calls have results that are converted
+/// to Rust style results.
 impl AsioWrapper {
-
-unsafe fn load(&mut self, raw: *mut i8) -> bool {
+    /// Load the driver.
+    /// Unloads the previous driver.
+    /// Sets state to Loaded on success.
+    unsafe fn load(&mut self, raw: *mut i8) -> bool {
         use AsioState::*;
         self.clean_up();
         if ai::load_asio_driver(raw) {
@@ -519,103 +668,121 @@ unsafe fn load(&mut self, raw: *mut i8) -> bool {
         } else {
             false
         }
-}
+    }
 
-unsafe fn unload(&mut self) {
+    /// Unloads the current driver from ASIO
+    unsafe fn unload(&mut self) {
         ai::remove_current_driver();
-}
+    }
 
-unsafe fn asio_init(&mut self, di: &mut ai::ASIODriverInfo) -> Result<(), AsioError> {
+    /// Initializes ASIO.
+    /// Needs to be already Loaded.
+    /// Initialized on success.
+    /// No-op if already Initialized or higher.
+    /// TODO should fail if Offline
+    unsafe fn asio_init(&mut self, di: &mut ai::ASIODriverInfo) -> Result<(), AsioError> {
         if let AsioState::Loaded = self.state {
             let result = ai::ASIOInit(di);
             asio_result!(result)
                 .map(|_| self.state = AsioState::Initialized)
-            .map_err(|e| {
-                self.state = AsioState::Offline;
-                e
-            })
-    }else{
+        } else {
             Ok(())
         }
-}
+    }
 
-unsafe fn asio_get_channels(&mut self, ins: &mut c_long, outs: &mut c_long) -> Result<(), AsioError> {
+    /// Gets the number of channels.
+    /// Needs to be atleast Loaded.
+    unsafe fn asio_get_channels(
+        &mut self, ins: &mut c_long, outs: &mut c_long,
+    ) -> Result<(), AsioError> {
         if let AsioState::Offline = self.state {
             Err(AsioError::NoDrivers)
         } else {
             let result = ai::ASIOGetChannels(ins, outs);
             asio_result!(result)
         }
-}
+    }
 
-unsafe fn asio_get_sample_rate(&mut self, rate: &mut c_double) -> Result<(), AsioError> {
+    /// Gets the sample rate.
+    /// Needs to be atleast Loaded.
+    unsafe fn asio_get_sample_rate(&mut self, rate: &mut c_double) -> Result<(), AsioError> {
         if let AsioState::Offline = self.state {
             Err(AsioError::NoDrivers)
         } else {
             let result = ai::get_sample_rate(rate);
             asio_result!(result)
         }
-}
+    }
 
-unsafe fn asio_set_sample_rate(&mut self, rate: c_double) -> Result<(), AsioError> {
+    /// Sets the sample rate.
+    /// Needs to be atleast Loaded.
+    unsafe fn asio_set_sample_rate(&mut self, rate: c_double) -> Result<(), AsioError> {
         if let AsioState::Offline = self.state {
             Err(AsioError::NoDrivers)
         } else {
             let result = ai::set_sample_rate(rate);
             asio_result!(result)
         }
-}
+    }
 
-unsafe fn asio_can_sample_rate(&mut self, rate: c_double) -> Result<(), AsioError> {
+    /// Queries if the sample rate is possible.
+    /// Needs to be atleast Loaded.
+    unsafe fn asio_can_sample_rate(&mut self, rate: c_double) -> Result<(), AsioError> {
         if let AsioState::Offline = self.state {
             Err(AsioError::NoDrivers)
         } else {
             let result = ai::can_sample_rate(rate);
             asio_result!(result)
         }
-}
+    }
 
-unsafe fn asio_get_channel_info(&mut self, ci: &mut ai::ASIOChannelInfo) -> Result<(), AsioError> {
+    /// Get information about a channel.
+    /// Needs to be atleast Loaded.
+    unsafe fn asio_get_channel_info(
+        &mut self, ci: &mut ai::ASIOChannelInfo,
+    ) -> Result<(), AsioError> {
         if let AsioState::Offline = self.state {
             Err(AsioError::NoDrivers)
         } else {
             let result = ai::ASIOGetChannelInfo(ci);
             asio_result!(result)
         }
-}
+    }
     
-unsafe fn asio_get_buffer_size(
-    &mut self, 
-    min_b_size: &mut c_long, max_b_size: &mut c_long, pref_b_size: &mut c_long, grans: &mut c_long,
-) -> Result<(), AsioError> {
+    /// Gets the buffer sizes.
+    /// Needs to be atleast Loaded.
+    unsafe fn asio_get_buffer_size(
+        &mut self, min_b_size: &mut c_long, max_b_size: &mut c_long, pref_b_size: &mut c_long,
+        grans: &mut c_long,
+    ) -> Result<(), AsioError> {
         if let AsioState::Offline = self.state {
             Err(AsioError::NoDrivers)
         } else {
-        let result = ai::ASIOGetBufferSize(
-            min_b_size,
-            max_b_size,
-            pref_b_size,
-            grans,
-        );
+            let result = ai::ASIOGetBufferSize(min_b_size, max_b_size, pref_b_size, grans);
             asio_result!(result)
         }
-}
+    }
 
-unsafe fn asio_create_buffers(
-    &mut self, 
-    buffer_info_convert: *mut ai::ASIOBufferInfo, num_channels: i32, pref_b_size: c_long,
-    callbacks_convert: &mut ai::ASIOCallbacks,
-) -> Result<(), AsioError> {
+    /// Creates the buffers.
+    /// Needs to be atleast Loaded.
+    /// If Running or Prepared then old buffers
+    /// will be destoryed.
+    unsafe fn asio_create_buffers(
+        &mut self, buffer_info_convert: *mut ai::ASIOBufferInfo, num_channels: i32,
+        pref_b_size: c_long, callbacks_convert: &mut ai::ASIOCallbacks,
+    ) -> Result<(), AsioError> {
         use AsioState::*;
         match self.state {
             Offline | Loaded => return Err(AsioError::NoDrivers),
             Running => {
                 self.asio_stop().expect("Asio failed to stop");
-            self.asio_dispose_buffers().expect("Failed to dispose buffers");
+                self.asio_dispose_buffers()
+                    .expect("Failed to dispose buffers");
                 self.state = Initialized;
             },
             Prepared => {
-            self.asio_dispose_buffers().expect("Failed to dispose buffers");
+                self.asio_dispose_buffers()
+                    .expect("Failed to dispose buffers");
                 self.state = Initialized;
             },
             _ => (),
@@ -626,11 +793,13 @@ unsafe fn asio_create_buffers(
             pref_b_size,
             callbacks_convert,
         );
-    asio_result!(result)
-        .map(|_| self.state = AsioState::Prepared)
-}
+        asio_result!(result).map(|_| self.state = AsioState::Prepared)
+    }
 
-unsafe fn asio_dispose_buffers(&mut self) -> Result<(), AsioError> {
+    /// Releases buffers allocations.
+    /// Needs to be atleast Loaded.
+    /// No op if already released.
+    unsafe fn asio_dispose_buffers(&mut self) -> Result<(), AsioError> {
         use AsioState::*;
         match self.state {
             Offline | Loaded => return Err(AsioError::NoDrivers),
@@ -638,22 +807,24 @@ unsafe fn asio_dispose_buffers(&mut self) -> Result<(), AsioError> {
             Initialized => return Ok(()),
         }
         let result = ai::ASIODisposeBuffers();
-    asio_result!(result)
-        .map(|_| self.state = AsioState::Initialized)
-}
+        asio_result!(result).map(|_| self.state = AsioState::Initialized)
+    }
 
-unsafe fn asio_exit(&mut self) -> Result<(), AsioError> {
+    /// Closes down ASIO.
+    /// Needs to be atleast Loaded.
+    unsafe fn asio_exit(&mut self) -> Result<(), AsioError> {
         use AsioState::*;
         match self.state {
             Offline | Loaded => return Err(AsioError::NoDrivers),
             _ => (),
         }
         let result = ai::ASIOExit();
-    asio_result!(result)
-        .map(|_| self.state = AsioState::Offline)
-}
+        asio_result!(result).map(|_| self.state = AsioState::Offline)
+    }
 
-unsafe fn asio_start(&mut self) -> Result<(), AsioError> {
+    /// Starts ASIO streams playing.
+    /// Needs to be atleast Initialized.
+    unsafe fn asio_start(&mut self) -> Result<(), AsioError> {
         use AsioState::*;
         match self.state {
             Offline | Loaded | Initialized => return Err(AsioError::NoDrivers),
@@ -661,11 +832,13 @@ unsafe fn asio_start(&mut self) -> Result<(), AsioError> {
             Prepared => (),
         }
         let result = ai::ASIOStart();
-    asio_result!(result)
-        .map(|_| self.state = AsioState::Running)
-}
+        asio_result!(result).map(|_| self.state = AsioState::Running)
+    }
 
-unsafe fn asio_stop(&mut self) -> Result<(), AsioError> {
+    /// Stops ASIO streams playing.
+    /// Needs to be Running.
+    /// No-op if already stopped.
+    unsafe fn asio_stop(&mut self) -> Result<(), AsioError> {
         use AsioState::*;
         match self.state {
             Offline | Loaded => return Err(AsioError::NoDrivers),
@@ -673,11 +846,12 @@ unsafe fn asio_stop(&mut self) -> Result<(), AsioError> {
             Initialized | Prepared => return Ok(()),
         }
         let result = ai::ASIOStop();
-    asio_result!(result)
-        .map(|_| self.state = AsioState::Prepared)
-}
+        asio_result!(result).map(|_| self.state = AsioState::Prepared)
+    }
 
-fn clean_up(&mut self) {
+    /// Cleans up the drivers based
+    /// on the current state of the driver.
+    fn clean_up(&mut self) {
         match self.state {
             AsioState::Offline => (),
             AsioState::Loaded => {
@@ -696,7 +870,8 @@ fn clean_up(&mut self) {
             },
             AsioState::Prepared => {
                 unsafe {
-                self.asio_dispose_buffers().expect("Failed to dispose buffers");
+                    self.asio_dispose_buffers()
+                        .expect("Failed to dispose buffers");
                     self.asio_exit().expect("Failed to exit asio");
                     self.unload();
                 }
@@ -705,12 +880,13 @@ fn clean_up(&mut self) {
             AsioState::Running => {
                 unsafe {
                     self.asio_stop().expect("Asio failed to stop");
-                self.asio_dispose_buffers().expect("Failed to dispose buffers");
+                    self.asio_dispose_buffers()
+                        .expect("Failed to dispose buffers");
                     self.asio_exit().expect("Failed to exit asio");
                     self.unload();
                 }
                 self.state = AsioState::Offline;
             },
         }
-}
+    }
 }