Add rustdoc links in most of the documentation (#682)

* Add rustdoc links in most of the documentation

Additionally, fix a couple of references to old
renamed types still lingering in the docs :)

Fixes #650

* Rustfmt on documentation changes

* Make docs for impl_platform_host not build example
This commit is contained in:
alichay 2022-11-04 15:57:23 -05:00 • committed by GitHub
parent 29999e6857
commit 7e17373e31
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 124 additions and 100 deletions

View file

@ -26,7 +26,7 @@ pub struct BackendSpecificError {
/// An error that might occur while attempting to enumerate the available devices on a system. /// An error that might occur while attempting to enumerate the available devices on a system.
#[derive(Debug, Error)] #[derive(Debug, Error)]
pub enum DevicesError { pub enum DevicesError {
/// See the `BackendSpecificError` docs for more information about this error variant. /// See the [`BackendSpecificError`] docs for more information about this error variant.
#[error("{err}")] #[error("{err}")]
BackendSpecific { BackendSpecific {
#[from] #[from]
@ -37,7 +37,7 @@ pub enum DevicesError {
/// An error that may occur while attempting to retrieve a device name. /// An error that may occur while attempting to retrieve a device name.
#[derive(Debug, Error)] #[derive(Debug, Error)]
pub enum DeviceNameError { pub enum DeviceNameError {
/// See the `BackendSpecificError` docs for more information about this error variant. /// See the [`BackendSpecificError`] docs for more information about this error variant.
#[error("{err}")] #[error("{err}")]
BackendSpecific { BackendSpecific {
#[from] #[from]
@ -57,7 +57,7 @@ pub enum SupportedStreamConfigsError {
"Invalid argument passed to the backend. For example, this happens when trying to read capture capabilities when the device does not support it." "Invalid argument passed to the backend. For example, this happens when trying to read capture capabilities when the device does not support it."
)] )]
InvalidArgument, InvalidArgument,
/// See the `BackendSpecificError` docs for more information about this error variant. /// See the [`BackendSpecificError`] docs for more information about this error variant.
#[error("{err}")] #[error("{err}")]
BackendSpecific { BackendSpecific {
#[from] #[from]
@ -65,7 +65,7 @@ pub enum SupportedStreamConfigsError {
}, },
} }
/// May occur when attempting to request the default input or output stream format from a `Device`. /// May occur when attempting to request the default input or output stream format from a [`Device`](crate::Device).
#[derive(Debug, Error)] #[derive(Debug, Error)]
pub enum DefaultStreamConfigError { pub enum DefaultStreamConfigError {
/// The device no longer exists. This can happen if the device is disconnected while the /// The device no longer exists. This can happen if the device is disconnected while the
@ -75,7 +75,7 @@ pub enum DefaultStreamConfigError {
/// Returned if e.g. the default input format was requested on an output-only audio device. /// Returned if e.g. the default input format was requested on an output-only audio device.
#[error("The requested stream type is not supported by the device.")] #[error("The requested stream type is not supported by the device.")]
StreamTypeNotSupported, StreamTypeNotSupported,
/// See the `BackendSpecificError` docs for more information about this error variant. /// See the [`BackendSpecificError`] docs for more information about this error variant.
#[error("{err}")] #[error("{err}")]
BackendSpecific { BackendSpecific {
#[from] #[from]
@ -83,7 +83,7 @@ pub enum DefaultStreamConfigError {
}, },
} }
/// Error that can happen when creating a `Stream`. /// Error that can happen when creating a [`Stream`](crate::Stream).
#[derive(Debug, Error)] #[derive(Debug, Error)]
pub enum BuildStreamError { pub enum BuildStreamError {
/// The device no longer exists. This can happen if the device is disconnected while the /// The device no longer exists. This can happen if the device is disconnected while the
@ -102,7 +102,7 @@ pub enum BuildStreamError {
/// Occurs if adding a new Stream ID would cause an integer overflow. /// Occurs if adding a new Stream ID would cause an integer overflow.
#[error("Adding a new stream ID would cause an overflow")] #[error("Adding a new stream ID would cause an overflow")]
StreamIdOverflow, StreamIdOverflow,
/// See the `BackendSpecificError` docs for more information about this error variant. /// See the [`BackendSpecificError`] docs for more information about this error variant.
#[error("{err}")] #[error("{err}")]
BackendSpecific { BackendSpecific {
#[from] #[from]
@ -110,7 +110,7 @@ pub enum BuildStreamError {
}, },
} }
/// Errors that might occur when calling `play_stream`. /// Errors that might occur when calling [`Stream::play()`](crate::traits::StreamTrait::play).
/// ///
/// As of writing this, only macOS may immediately return an error while calling this method. This /// As of writing this, only macOS may immediately return an error while calling this method. This
/// is because both the alsa and wasapi backends only enqueue these commands and do not process /// is because both the alsa and wasapi backends only enqueue these commands and do not process
@ -120,7 +120,7 @@ pub enum PlayStreamError {
/// The device associated with the stream is no longer available. /// The device associated with the stream is no longer available.
#[error("the device associated with the stream is no longer available")] #[error("the device associated with the stream is no longer available")]
DeviceNotAvailable, DeviceNotAvailable,
/// See the `BackendSpecificError` docs for more information about this error variant. /// See the [`BackendSpecificError`] docs for more information about this error variant.
#[error("{err}")] #[error("{err}")]
BackendSpecific { BackendSpecific {
#[from] #[from]
@ -128,7 +128,7 @@ pub enum PlayStreamError {
}, },
} }
/// Errors that might occur when calling `pause_stream`. /// Errors that might occur when calling [`Stream::pause()`](crate::traits::StreamTrait::pause).
/// ///
/// As of writing this, only macOS may immediately return an error while calling this method. This /// As of writing this, only macOS may immediately return an error while calling this method. This
/// is because both the alsa and wasapi backends only enqueue these commands and do not process /// is because both the alsa and wasapi backends only enqueue these commands and do not process
@ -138,7 +138,7 @@ pub enum PauseStreamError {
/// The device associated with the stream is no longer available. /// The device associated with the stream is no longer available.
#[error("the device associated with the stream is no longer available")] #[error("the device associated with the stream is no longer available")]
DeviceNotAvailable, DeviceNotAvailable,
/// See the `BackendSpecificError` docs for more information about this error variant. /// See the [`BackendSpecificError`] docs for more information about this error variant.
#[error("{err}")] #[error("{err}")]
BackendSpecific { BackendSpecific {
#[from] #[from]
@ -153,7 +153,7 @@ pub enum StreamError {
/// program is running. /// program is running.
#[error("The requested device is no longer available. For example, it has been unplugged.")] #[error("The requested device is no longer available. For example, it has been unplugged.")]
DeviceNotAvailable, DeviceNotAvailable,
/// See the `BackendSpecificError` docs for more information about this error variant. /// See the [`BackendSpecificError`] docs for more information about this error variant.
#[error("{err}")] #[error("{err}")]
BackendSpecific { BackendSpecific {
#[from] #[from]

View file

@ -2,28 +2,29 @@
//! //!
//! Here are some concepts cpal exposes: //! Here are some concepts cpal exposes:
//! //!
//! - A [**Host**](./struct.Host.html) provides access to the available audio devices on the system. //! - A [`Host`] provides access to the available audio devices on the system.
//! Some platforms have more than one host available, but every platform supported by CPAL has at //! Some platforms have more than one host available, but every platform supported by CPAL has at
//! least one [**DefaultHost**](./struct.Host.html) that is guaranteed to be available. //! least one [default_host] that is guaranteed to be available.
//! - A [**Device**](./struct.Device.html) is an audio device that may have any number of input and //! - A [`Device`] is an audio device that may have any number of input and
//! output streams. //! output streams.
//! - A [**Stream**](./struct.Stream.html) is an open flow of audio data. Input streams allow you to //! - A [`Stream`] is an open flow of audio data. Input streams allow you to
//! receive audio data, output streams allow you to play audio data. You must choose which //! receive audio data, output streams allow you to play audio data. You must choose which
//! **Device** will run your stream before you can create one. Often, a default device can be //! [Device] will run your stream before you can create one. Often, a default device can be
//! retrieved via the **Host**. //! retrieved via the [Host].
//! //!
//! The first step is to initialise the `Host`: //! The first step is to initialise the [`Host`]:
//! //!
//! ``` //! ```
//! use cpal::traits::HostTrait; //! use cpal::traits::HostTrait;
//! let host = cpal::default_host(); //! let host = cpal::default_host();
//! ``` //! ```
//! //!
//! Then choose an available `Device`. The easiest way is to use the default input or output //! Then choose an available [`Device`]. The easiest way is to use the default input or output
//! `Device` via the `default_input_device()` or `default_output_device()` functions. Alternatively //! `Device` via the [`default_input_device()`] or [`default_output_device()`] methods on `host`.
//! you can enumerate all the available devices with the `devices()` function. Beware that the //!
//! `default_*_device()` functions return an `Option` in case no device is available for that //! Alternatively, you can enumerate all the available devices with the [`devices()`] method.
//! stream type on the system. //! Beware that the `default_*_device()` functions return an `Option<Device>` in case no device
//! is available for that stream type on the system.
//! //!
//! ```no_run //! ```no_run
//! # use cpal::traits::HostTrait; //! # use cpal::traits::HostTrait;
@ -32,15 +33,18 @@
//! ``` //! ```
//! //!
//! Before we can create a stream, we must decide what the configuration of the audio stream is //! Before we can create a stream, we must decide what the configuration of the audio stream is
//! going to be. You can query all the supported configurations with the //! going to be.
//! `supported_input_configs()` and `supported_output_configs()` methods. These produce a list of //! You can query all the supported configurations with the
//! `SupportedStreamConfigRange` structs which can later be turned into actual //! [`supported_input_configs()`] and [`supported_output_configs()`] methods.
//! `SupportedStreamConfig` structs. If you don't want to query the list of configs, you can also //! These produce a list of [`SupportedStreamConfigRange`] structs which can later be turned into
//! build your own `StreamConfig` manually, but doing so could lead to an error when building the //! actual [`SupportedStreamConfig`] structs.
//! stream if the config is not supported by the device.
//! //!
//! > **Note**: the `supported_input/output_configs()` methods could return an error for example if //! If you don't want to query the list of configs,
//! > the device has been disconnected. //! you can also build your own [`StreamConfig`] manually, but doing so could lead to an error when
//! building the stream if the config is not supported by the device.
//!
//! > **Note**: the `supported_input/output_configs()` methods
//! > could return an error for example if the device has been disconnected.
//! //!
//! ```no_run //! ```no_run
//! use cpal::traits::{DeviceTrait, HostTrait}; //! use cpal::traits::{DeviceTrait, HostTrait};
@ -74,8 +78,8 @@
//! ``` //! ```
//! //!
//! While the stream is running, the selected audio device will periodically call the data callback //! While the stream is running, the selected audio device will periodically call the data callback
//! that was passed to the function. The callback is passed an instance of either `&Data` or //! that was passed to the function. The callback is passed an instance of either [`&Data` or
//! `&mut Data` depending on whether the stream is an input stream or output stream respectively. //! `&mut Data`](Data) depending on whether the stream is an input stream or output stream respectively.
//! //!
//! > **Note**: Creating and running a stream will *not* block the thread. On modern platforms, the //! > **Note**: Creating and running a stream will *not* block the thread. On modern platforms, the
//! > given callback is called by a dedicated, high-priority thread responsible for delivering //! > given callback is called by a dedicated, high-priority thread responsible for delivering
@ -112,7 +116,7 @@
//! ``` //! ```
//! //!
//! Not all platforms automatically run the stream upon creation. To ensure the stream has started, //! Not all platforms automatically run the stream upon creation. To ensure the stream has started,
//! we can use `Stream::play`. //! we can use [`Stream::play`](traits::StreamTrait::play).
//! //!
//! ```no_run //! ```no_run
//! # use cpal::traits::{DeviceTrait, HostTrait, StreamTrait}; //! # use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
@ -142,6 +146,12 @@
//! # let stream = device.build_output_stream_raw(&config, sample_format, data_fn, err_fn, None).unwrap(); //! # let stream = device.build_output_stream_raw(&config, sample_format, data_fn, err_fn, None).unwrap();
//! stream.pause().unwrap(); //! stream.pause().unwrap();
//! ``` //! ```
//!
//! [`default_input_device()`]: traits::HostTrait::default_input_device
//! [`default_output_device()`]: traits::HostTrait::default_output_device
//! [`devices()`]: traits::HostTrait::devices
//! [`supported_input_configs()`]: traits::DeviceTrait::supported_input_configs
//! [`supported_output_configs()`]: traits::DeviceTrait::supported_output_configs
#![recursion_limit = "2048"] #![recursion_limit = "2048"]
@ -212,11 +222,15 @@ pub type FrameCount = u32;
/// The buffer size used by the device. /// The buffer size used by the device.
/// ///
/// Default is used when no specific buffer size is set and uses the default /// [`Default`] is used when no specific buffer size is set and uses the default
/// behavior of the given host. Note, the default buffer size may be surprisingly /// behavior of the given host. Note, the default buffer size may be surprisingly
/// large, leading to latency issues. If low latency is desired, Fixed(BufferSize) /// large, leading to latency issues. If low latency is desired, [`Fixed(FrameCount)`]
/// should be used in accordance with the SupportedBufferSize range produced by /// should be used in accordance with the [`SupportedBufferSize`] range produced by
/// the SupportedStreamConfig API. /// the [`SupportedStreamConfig`] API.
///
/// [`Default`]: BufferSize::Default
/// [`Fixed(FrameCount)`]: BufferSize::Fixed
/// [`SupportedStreamConfig`]: SupportedStreamConfig::buffer_size
#[derive(Clone, Copy, Debug, Eq, PartialEq)] #[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum BufferSize { pub enum BufferSize {
Default, Default,
@ -264,7 +278,7 @@ pub enum SupportedBufferSize {
} }
/// Describes a range of supported stream configurations, retrieved via the /// Describes a range of supported stream configurations, retrieved via the
/// `Device::supported_input/output_configs` method. /// [`Device::supported_input/output_configs`](traits::DeviceTrait#required-methods) method.
#[derive(Debug, Clone, PartialEq, Eq)] #[derive(Debug, Clone, PartialEq, Eq)]
pub struct SupportedStreamConfigRange { pub struct SupportedStreamConfigRange {
pub(crate) channels: ChannelCount, pub(crate) channels: ChannelCount,
@ -279,7 +293,8 @@ pub struct SupportedStreamConfigRange {
} }
/// Describes a single supported stream configuration, retrieved via either a /// Describes a single supported stream configuration, retrieved via either a
/// `SupportedStreamConfigRange` instance or one of the `Device::default_input/output_config` methods. /// [`SupportedStreamConfigRange`] instance or one of the
/// [`Device::default_input/output_config`](traits::DeviceTrait#required-methods) methods.
#[derive(Debug, Clone, PartialEq, Eq)] #[derive(Debug, Clone, PartialEq, Eq)]
pub struct SupportedStreamConfig { pub struct SupportedStreamConfig {
channels: ChannelCount, channels: ChannelCount,
@ -306,7 +321,7 @@ pub struct Data {
/// 2. The same time source used to generate timestamps for a stream's underlying audio data /// 2. The same time source used to generate timestamps for a stream's underlying audio data
/// callback. /// callback.
/// ///
/// **StreamInstant** represents a duration since some unspecified origin occurring either before /// `StreamInstant` represents a duration since some unspecified origin occurring either before
/// or equal to the moment the stream from which it was created begins. /// or equal to the moment the stream from which it was created begins.
/// ///
/// ## Host `StreamInstant` Sources /// ## Host `StreamInstant` Sources
@ -427,7 +442,7 @@ impl StreamInstant {
/// Returns the instant in time one `duration` ago. /// Returns the instant in time one `duration` ago.
/// ///
/// Returns `None` if the resulting instant would underflow. As a result, it is important to /// Returns `None` if the resulting instant would underflow. As a result, it is important to
/// consider that on some platforms the `StreamInstant` may begin at `0` from the moment the /// consider that on some platforms the [`StreamInstant`] may begin at `0` from the moment the
/// source stream is created. /// source stream is created.
pub fn sub(&self, duration: Duration) -> Option<Self> { pub fn sub(&self, duration: Duration) -> Option<Self> {
self.as_nanos() self.as_nanos()
@ -515,24 +530,24 @@ impl Data {
/// The full length of the buffer in samples. /// The full length of the buffer in samples.
/// ///
/// The returned length is the same length as the slice of type `T` that would be returned via /// The returned length is the same length as the slice of type `T` that would be returned via
/// `as_slice` given a sample type that matches the inner sample format. /// [`as_slice`](Self::as_slice) given a sample type that matches the inner sample format.
pub fn len(&self) -> usize { pub fn len(&self) -> usize {
self.len self.len
} }
/// The raw slice of memory representing the underlying audio data as a slice of bytes. /// The raw slice of memory representing the underlying audio data as a slice of bytes.
/// ///
/// It is up to the user to interpret the slice of memory based on `Data::sample_format`. /// It is up to the user to interpret the slice of memory based on [`Data::sample_format`].
pub fn bytes(&self) -> &[u8] { pub fn bytes(&self) -> &[u8] {
let len = self.len * self.sample_format.sample_size(); let len = self.len * self.sample_format.sample_size();
// The safety of this block relies on correct construction of the `Data` instance. See // The safety of this block relies on correct construction of the `Data` instance.
// the unsafe `from_parts` constructor for these requirements. // See the unsafe `from_parts` constructor for these requirements.
unsafe { std::slice::from_raw_parts(self.data as *const u8, len) } unsafe { std::slice::from_raw_parts(self.data as *const u8, len) }
} }
/// The raw slice of memory representing the underlying audio data as a slice of bytes. /// The raw slice of memory representing the underlying audio data as a slice of bytes.
/// ///
/// It is up to the user to interpret the slice of memory based on `Data::sample_format`. /// It is up to the user to interpret the slice of memory based on [`Data::sample_format`].
pub fn bytes_mut(&mut self) -> &mut [u8] { pub fn bytes_mut(&mut self) -> &mut [u8] {
let len = self.len * self.sample_format.sample_size(); let len = self.len * self.sample_format.sample_size();
// The safety of this block relies on correct construction of the `Data` instance. See // The safety of this block relies on correct construction of the `Data` instance. See
@ -615,10 +630,12 @@ impl SupportedStreamConfigRange {
self.sample_format self.sample_format
} }
/// Retrieve a `SupportedStreamConfig` with the given sample rate and buffer size. /// Retrieve a [`SupportedStreamConfig`] with the given sample rate and buffer size.
/// ///
/// **panic!**s if the given `sample_rate` is outside the range specified within this /// # Panics
/// `SupportedStreamConfigRange` instance. ///
/// Panics if the given `sample_rate` is outside the range specified within this
/// [`SupportedStreamConfigRange`] instance.
pub fn with_sample_rate(self, sample_rate: SampleRate) -> SupportedStreamConfig { pub fn with_sample_rate(self, sample_rate: SampleRate) -> SupportedStreamConfig {
assert!(self.min_sample_rate <= sample_rate && sample_rate <= self.max_sample_rate); assert!(self.min_sample_rate <= sample_rate && sample_rate <= self.max_sample_rate);
SupportedStreamConfig { SupportedStreamConfig {
@ -629,7 +646,7 @@ impl SupportedStreamConfigRange {
} }
} }
/// Turns this `SupportedStreamConfigRange` into a `SupportedStreamConfig` corresponding to the maximum samples rate. /// Turns this [`SupportedStreamConfigRange`] into a [`SupportedStreamConfig`] corresponding to the maximum samples rate.
#[inline] #[inline]
pub fn with_max_sample_rate(self) -> SupportedStreamConfig { pub fn with_max_sample_rate(self) -> SupportedStreamConfig {
SupportedStreamConfig { SupportedStreamConfig {
@ -640,7 +657,7 @@ impl SupportedStreamConfigRange {
} }
} }
/// A comparison function which compares two `SupportedStreamConfigRange`s in terms of their priority of /// A comparison function which compares two [`SupportedStreamConfigRange`]s in terms of their priority of
/// use as a default stream format. /// use as a default stream format.
/// ///
/// Some backends do not provide a default stream format for their audio devices. In these /// Some backends do not provide a default stream format for their audio devices. In these

View file

@ -1,35 +1,37 @@
//! Platform-specific items. //! Platform-specific items.
//! //!
//! This module also contains the implementation of the platform's dynamically dispatched `Host` //! This module also contains the implementation of the platform's dynamically dispatched [`Host`]
//! type and its associated `Device`, `StreamId` and other associated types. These //! type and its associated [`Device`], [`Stream`] and other associated types. These
//! types are useful in the case that users require switching between audio host APIs at runtime. //! types are useful in the case that users require switching between audio host APIs at runtime.
#[doc(inline)] #[doc(inline)]
pub use self::platform_impl::*; pub use self::platform_impl::*;
// A macro to assist with implementing a platform's dynamically dispatched `Host` type. /// A macro to assist with implementing a platform's dynamically dispatched [`Host`] type.
// ///
// These dynamically dispatched types are necessary to allow for users to switch between hosts at /// These dynamically dispatched types are necessary to allow for users to switch between hosts at
// runtime. /// runtime.
// ///
// For example the invocation `impl_platform_host(Wasapi wasapi "WASAPI", Asio asio "ASIO")`, /// For example the invocation `impl_platform_host(Wasapi wasapi "WASAPI", Asio asio "ASIO")`,
// this macro should expand to: /// this macro should expand to:
// ///
// ``` // This sample code block is marked as text because it's not a valid test,
// pub enum HostId { // it's just illustrative. (see rust issue #96573)
// Wasapi, /// ```text
// Asio, /// pub enum HostId {
// } /// Wasapi,
// /// Asio,
// pub enum Host { /// }
// Wasapi(crate::host::wasapi::Host), ///
// Asio(crate::host::asio::Host), /// pub enum Host {
// } /// Wasapi(crate::host::wasapi::Host),
// ``` /// Asio(crate::host::asio::Host),
// /// }
// And so on for Device, Devices, Host, StreamId, SupportedInputConfigs, /// ```
// SupportedOutputConfigs and all their necessary trait implementations. ///
// ``` /// And so on for Device, Devices, Host, Stream, SupportedInputConfigs,
/// SupportedOutputConfigs and all their necessary trait implementations.
///
macro_rules! impl_platform_host { macro_rules! impl_platform_host {
($($(#[cfg($feat: meta)])? $HostVariant:ident $host_mod:ident $host_name:literal),*) => { ($($(#[cfg($feat: meta)])? $HostVariant:ident $host_mod:ident $host_name:literal),*) => {
/// All hosts supported by CPAL on this platform. /// All hosts supported by CPAL on this platform.
@ -40,27 +42,27 @@ macro_rules! impl_platform_host {
)* )*
]; ];
/// The platform's dynamically dispatched **Host** type. /// The platform's dynamically dispatched `Host` type.
/// ///
/// An instance of this **Host** type may represent one of the **Host**s available /// An instance of this `Host` type may represent one of the `Host`s available
/// on the platform. /// on the platform.
/// ///
/// Use this type if you require switching between available hosts at runtime. /// Use this type if you require switching between available hosts at runtime.
/// ///
/// This type may be constructed via the **host_from_id** function. **HostId**s may /// This type may be constructed via the [`host_from_id`] function. [`HostId`]s may
/// be acquired via the **ALL_HOSTS** const, and the **available_hosts** function. /// be acquired via the [`ALL_HOSTS`] const, and the [`available_hosts`] function.
pub struct Host(HostInner); pub struct Host(HostInner);
/// The **Device** implementation associated with the platform's dynamically dispatched /// The `Device` implementation associated with the platform's dynamically dispatched
/// **Host** type. /// [`Host`] type.
pub struct Device(DeviceInner); pub struct Device(DeviceInner);
/// The **Devices** iterator associated with the platform's dynamically dispatched **Host** /// The `Devices` iterator associated with the platform's dynamically dispatched [`Host`]
/// type. /// type.
pub struct Devices(DevicesInner); pub struct Devices(DevicesInner);
/// The **Stream** implementation associated with the platform's dynamically dispatched /// The `Stream` implementation associated with the platform's dynamically dispatched
/// **Host** type. /// [`Host`] type.
// Streams cannot be `Send` or `Sync` if we plan to support Android's AAudio API. This is // Streams cannot be `Send` or `Sync` if we plan to support Android's AAudio API. This is
// because the stream API is not thread-safe, and the API prohibits calling certain // because the stream API is not thread-safe, and the API prohibits calling certain
// functions within the callback. // functions within the callback.
@ -68,12 +70,12 @@ macro_rules! impl_platform_host {
// TODO: Confirm this and add more specific detail and references. // TODO: Confirm this and add more specific detail and references.
pub struct Stream(StreamInner, crate::platform::NotSendSyncAcrossAllPlatforms); pub struct Stream(StreamInner, crate::platform::NotSendSyncAcrossAllPlatforms);
/// The **SupportedInputConfigs** iterator associated with the platform's dynamically /// The `SupportedInputConfigs` iterator associated with the platform's dynamically
/// dispatched **Host** type. /// dispatched [`Host`] type.
pub struct SupportedInputConfigs(SupportedInputConfigsInner); pub struct SupportedInputConfigs(SupportedInputConfigsInner);
/// The **SupportedOutputConfigs** iterator associated with the platform's dynamically /// The `SupportedOutputConfigs` iterator associated with the platform's dynamically
/// dispatched **Host** type. /// dispatched [`Host`] type.
pub struct SupportedOutputConfigs(SupportedOutputConfigsInner); pub struct SupportedOutputConfigs(SupportedOutputConfigsInner);
/// Unique identifier for available hosts on the platform. /// Unique identifier for available hosts on the platform.
@ -85,7 +87,7 @@ macro_rules! impl_platform_host {
)* )*
} }
/// Contains a platform specific `Device` implementation. /// Contains a platform specific [`Device`] implementation.
pub enum DeviceInner { pub enum DeviceInner {
$( $(
$(#[cfg($feat)])? $(#[cfg($feat)])?
@ -93,7 +95,7 @@ macro_rules! impl_platform_host {
)* )*
} }
/// Contains a platform specific `Devices` implementation. /// Contains a platform specific [`Devices`] implementation.
pub enum DevicesInner { pub enum DevicesInner {
$( $(
$(#[cfg($feat)])? $(#[cfg($feat)])?
@ -101,7 +103,7 @@ macro_rules! impl_platform_host {
)* )*
} }
/// Contains a platform specific `Host` implementation. /// Contains a platform specific [`Host`] implementation.
pub enum HostInner { pub enum HostInner {
$( $(
$(#[cfg($feat)])? $(#[cfg($feat)])?
@ -109,7 +111,7 @@ macro_rules! impl_platform_host {
)* )*
} }
/// Contains a platform specific `Stream` implementation. /// Contains a platform specific [`Stream`] implementation.
pub enum StreamInner { pub enum StreamInner {
$( $(
$(#[cfg($feat)])? $(#[cfg($feat)])?
@ -181,7 +183,7 @@ macro_rules! impl_platform_host {
} }
impl Host { impl Host {
/// The unique identifier associated with this host. /// The unique identifier associated with this `Host`.
pub fn id(&self) -> HostId { pub fn id(&self) -> HostId {
match self.0 { match self.0 {
$( $(

View file

@ -9,7 +9,7 @@ use crate::{
SupportedStreamConfigRange, SupportedStreamConfigsError, SupportedStreamConfigRange, SupportedStreamConfigsError,
}; };
/// A **Host** provides access to the available audio devices on the system. /// A [`Host`] provides access to the available audio devices on the system.
/// ///
/// Each platform may have a number of available hosts depending on the system, each with their own /// Each platform may have a number of available hosts depending on the system, each with their own
/// pros and cons. /// pros and cons.
@ -28,6 +28,8 @@ use crate::{
/// JACK is yet another host API that is more suitable to pro-audio applications, however it is /// JACK is yet another host API that is more suitable to pro-audio applications, however it is
/// less readily available by default in many Linux distributions and is known to be tricky to /// less readily available by default in many Linux distributions and is known to be tricky to
/// set up. /// set up.
///
/// [`Host`]: crate::Host
pub trait HostTrait { pub trait HostTrait {
/// The type used for enumerating available devices by the host. /// The type used for enumerating available devices by the host.
type Devices: Iterator<Item = Self::Device>; type Devices: Iterator<Item = Self::Device>;
@ -37,7 +39,7 @@ pub trait HostTrait {
/// Whether or not the host is available on the system. /// Whether or not the host is available on the system.
fn is_available() -> bool; fn is_available() -> bool;
/// An iterator yielding all `Device`s currently available to the host on the system. /// An iterator yielding all [`Device`](DeviceTrait)s currently available to the host on the system.
/// ///
/// Can be empty if the system does not support audio in general. /// Can be empty if the system does not support audio in general.
fn devices(&self) -> Result<Self::Devices, DevicesError>; fn devices(&self) -> Result<Self::Devices, DevicesError>;
@ -90,7 +92,10 @@ pub trait DeviceTrait {
type SupportedInputConfigs: Iterator<Item = SupportedStreamConfigRange>; type SupportedInputConfigs: Iterator<Item = SupportedStreamConfigRange>;
/// The iterator type yielding supported output stream formats. /// The iterator type yielding supported output stream formats.
type SupportedOutputConfigs: Iterator<Item = SupportedStreamConfigRange>; type SupportedOutputConfigs: Iterator<Item = SupportedStreamConfigRange>;
/// The stream type created by `build_input_stream_raw` and `build_output_stream_raw`. /// The stream type created by [`build_input_stream_raw`] and [`build_output_stream_raw`].
///
/// [`build_input_stream_raw`]: Self::build_input_stream_raw
/// [`build_output_stream_raw`]: Self::build_output_stream_raw
type Stream: StreamTrait; type Stream: StreamTrait;
/// The human-readable name of the device. /// The human-readable name of the device.
@ -199,7 +204,7 @@ pub trait DeviceTrait {
E: FnMut(StreamError) + Send + 'static; E: FnMut(StreamError) + Send + 'static;
} }
/// A stream created from `Device`, with methods to control playback. /// A stream created from [`Device`](DeviceTrait), with methods to control playback.
pub trait StreamTrait { pub trait StreamTrait {
/// Run the stream. /// Run the stream.
/// ///