Clean up docstrings and improve function names

Author: HEnquist

examples/sine_advanced.rs

@@ -5,9 +5,9 @@ extern crate coreaudio;
 
 use coreaudio::audio_unit::audio_format::LinearPcmFlags;
 use coreaudio::audio_unit::macos_helpers::{
-    audio_unit_from_device_id, find_matching_physical_format, get_default_device_id, get_owner_pid,
+    audio_unit_from_device_id, find_matching_physical_format, get_default_device_id, get_hogging_pid,
     get_supported_physical_stream_formats, set_device_physical_stream_format,
-    set_device_sample_rate, switch_ownership, AliveListener, RateListener,
+    set_device_sample_rate, toggle_hog_mode, AliveListener, RateListener,
 };
 use coreaudio::audio_unit::render_callback::{self, data};
 use coreaudio::audio_unit::{Element, SampleFormat, Scope, StreamFormat};
@@ -62,12 +62,12 @@ fn main() -> Result<(), coreaudio::Error> {
     let audio_unit_id = get_default_device_id(false).unwrap();
     let mut audio_unit = audio_unit_from_device_id(audio_unit_id, false)?;
 
-    let pid = get_owner_pid(audio_unit_id)?;
+    let pid = get_hogging_pid(audio_unit_id)?;
     if pid != -1 {
         println!("Device is owned by another process with pid {}!", pid);
     } else {
         println!("Device is free, trying to get exclusive access..");
-        let new_pid = switch_ownership(audio_unit_id)?;
+        let new_pid = toggle_hog_mode(audio_unit_id)?;
         let process_id = process::id();
         if new_pid == process_id as i32 {
             println!("We have exclusive access.");
@@ -198,12 +198,12 @@ fn main() -> Result<(), coreaudio::Error> {
         println!("alive state: {}", alive_listener.is_alive());
     }
 
-    // Release exclusive access, not really needed as the process anyway exits after this.
-    let owner_pid = get_owner_pid(audio_unit_id)?;
+    // Release exclusive access, not really needed as the process exits anyway after this.
+    let owner_pid = get_hogging_pid(audio_unit_id)?;
     let process_id = process::id();
     if owner_pid == process_id as i32 {
         println!("Releasing exclusive access");
-        let new_pid = switch_ownership(audio_unit_id)?;
+        let new_pid = toggle_hog_mode(audio_unit_id)?;
         if new_pid == -1 {
             println!("Exclusive access released.");
         } else {

src/audio_unit/macos_helpers.rs

@@ -728,11 +728,10 @@ impl AliveListener {
     }
 }
 
-/// Hog mode.
-/// Get the pid of the process that currently owns
-/// exclusive access to a device.
-/// A value of -1 means no process owns exclusive access.
-pub fn get_owner_pid(device_id: AudioDeviceID) -> Result<pid_t, Error> {
+/// Helper for hog mode (exclusive access).
+/// Get the pid of the process that currently owns exclusive access to a device.
+/// A pid value of -1 means no process owns exclusive access.
+pub fn get_hogging_pid(device_id: AudioDeviceID) -> Result<pid_t, Error> {
     // Get available formats.
     let property_address = AudioObjectPropertyAddress {
         mSelector: kAudioDevicePropertyHogMode,
@@ -756,14 +755,14 @@ pub fn get_owner_pid(device_id: AudioDeviceID) -> Result<pid_t, Error> {
     Ok(pid)
 }
 
-/// Hog mode.
-/// Switch the exclusive access to a device.
+/// Helper for hog mode (exclusive access).
+/// Toggle hog mode for a device.
 /// If no process owns exclusive access, then the calling process takes ownership.
 /// If the calling process already has ownership, this is released.
 /// If another process owns access, then nothing will happen.
 /// Returns the pid of the new owning process.
-/// A value of -1 means no process owns exclusive access.
-pub fn switch_ownership(device_id: AudioDeviceID) -> Result<pid_t, Error> {
+/// A pid value of -1 means no process owns exclusive access.
+pub fn toggle_hog_mode(device_id: AudioDeviceID) -> Result<pid_t, Error> {
     // Get available formats.
     let property_address = AudioObjectPropertyAddress {
         mSelector: kAudioDevicePropertyHogMode,