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.
#[derive(Debug, Error)]
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}")]
BackendSpecific {
#[from]
@ -37,7 +37,7 @@ pub enum DevicesError {
/// An error that may occur while attempting to retrieve a device name.
#[derive(Debug, Error)]
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}")]
BackendSpecific {
#[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."
)]
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}")]
BackendSpecific {
#[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)]
pub enum DefaultStreamConfigError {
/// 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.
#[error("The requested stream type is not supported by the device.")]
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}")]
BackendSpecific {
#[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)]
pub enum BuildStreamError {
/// 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.
#[error("Adding a new stream ID would cause an overflow")]
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}")]
BackendSpecific {
#[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
/// 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.
#[error("the device associated with the stream is no longer available")]
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}")]
BackendSpecific {
#[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
/// 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.
#[error("the device associated with the stream is no longer available")]
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}")]
BackendSpecific {
#[from]
@ -153,7 +153,7 @@ pub enum StreamError {
/// program is running.
#[error("The requested device is no longer available. For example, it has been unplugged.")]
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}")]
BackendSpecific {
#[from]

View file

@ -2,28 +2,29 @@
//!
//! 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
//! least one [**DefaultHost**](./struct.Host.html) that is guaranteed to be available.
//! - A [**Device**](./struct.Device.html) is an audio device that may have any number of input and
//! least one [default_host] that is guaranteed to be available.
//! - A [`Device`] is an audio device that may have any number of input and
//! 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
//! **Device** will run your stream before you can create one. Often, a default device can be
//! retrieved via the **Host**.
//! [Device] will run your stream before you can create one. Often, a default device can be
//! retrieved via the [Host].
//!
//! The first step is to initialise the `Host`:
//! The first step is to initialise the [`Host`]:
//!
//! ```
//! use cpal::traits::HostTrait;
//! let host = cpal::default_host();
//! ```
//!
//! 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
//! 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
//! stream type on the system.
//! 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()`] methods on `host`.
//!
//! Alternatively, you can enumerate all the available devices with the [`devices()`] method.
//! 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
//! # 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
//! going to be. You can query all the supported configurations with the
//! `supported_input_configs()` and `supported_output_configs()` methods. These produce a list of
//! `SupportedStreamConfigRange` structs which can later be turned into actual
//! `SupportedStreamConfig` structs. If you don't want to query the list of configs, 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.
//! going to be.
//! You can query all the supported configurations with the
//! [`supported_input_configs()`] and [`supported_output_configs()`] methods.
//! These produce a list of [`SupportedStreamConfigRange`] structs which can later be turned into
//! actual [`SupportedStreamConfig`] structs.
//!
//! > **Note**: the `supported_input/output_configs()` methods could return an error for example if
//! > the device has been disconnected.
//! If you don't want to query the list of configs,
//! 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
//! use cpal::traits::{DeviceTrait, HostTrait};
@ -74,8 +78,8 @@
//! ```
//!
//! 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
//! `&mut Data` depending on whether the stream is an input stream or output stream respectively.
//! that was passed to the function. The callback is passed an instance of either [`&Data` or
//! `&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
//! > 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,
//! we can use `Stream::play`.
//! we can use [`Stream::play`](traits::StreamTrait::play).
//!
//! ```no_run
//! # 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();
//! 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"]
@ -212,11 +222,15 @@ pub type FrameCount = u32;
/// 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
/// large, leading to latency issues. If low latency is desired, Fixed(BufferSize)
/// should be used in accordance with the SupportedBufferSize range produced by
/// the SupportedStreamConfig API.
/// large, leading to latency issues. If low latency is desired, [`Fixed(FrameCount)`]
/// should be used in accordance with the [`SupportedBufferSize`] range produced by
/// the [`SupportedStreamConfig`] API.
///
/// [`Default`]: BufferSize::Default
/// [`Fixed(FrameCount)`]: BufferSize::Fixed
/// [`SupportedStreamConfig`]: SupportedStreamConfig::buffer_size
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum BufferSize {
Default,
@ -264,7 +278,7 @@ pub enum SupportedBufferSize {
}
/// 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)]
pub struct SupportedStreamConfigRange {
pub(crate) channels: ChannelCount,
@ -279,7 +293,8 @@ pub struct SupportedStreamConfigRange {
}
/// 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)]
pub struct SupportedStreamConfig {
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
/// 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.
///
/// ## Host `StreamInstant` Sources
@ -427,7 +442,7 @@ impl StreamInstant {
/// Returns the instant in time one `duration` ago.
///
/// 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.
pub fn sub(&self, duration: Duration) -> Option<Self> {
self.as_nanos()
@ -515,24 +530,24 @@ impl Data {
/// 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
/// `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 {
self.len
}
/// 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] {
let len = self.len * self.sample_format.sample_size();
// The safety of this block relies on correct construction of the `Data` instance. See
// the unsafe `from_parts` constructor for these requirements.
// The safety of this block relies on correct construction of the `Data` instance.
// See the unsafe `from_parts` constructor for these requirements.
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.
///
/// 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] {
let len = self.len * self.sample_format.sample_size();
// The safety of this block relies on correct construction of the `Data` instance. See
@ -615,10 +630,12 @@ impl SupportedStreamConfigRange {
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
/// `SupportedStreamConfigRange` instance.
/// # Panics
///
/// 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 {
assert!(self.min_sample_rate <= sample_rate && sample_rate <= self.max_sample_rate);
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]
pub fn with_max_sample_rate(self) -> 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.
///
/// Some backends do not provide a default stream format for their audio devices. In these

View file

@ -1,35 +1,37 @@
//! Platform-specific items.
//!
//! This module also contains the implementation of the platform's dynamically dispatched `Host`
//! type and its associated `Device`, `StreamId` and other associated types. These
//! This module also contains the implementation of the platform's dynamically dispatched [`Host`]
//! 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.
#[doc(inline)]
pub use self::platform_impl::*;
// 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
// runtime.
//
// For example the invocation `impl_platform_host(Wasapi wasapi "WASAPI", Asio asio "ASIO")`,
// this macro should expand to:
//
// ```
// pub enum HostId {
// Wasapi,
// Asio,
// }
//
// 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.
// ```
/// 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
/// runtime.
///
/// For example the invocation `impl_platform_host(Wasapi wasapi "WASAPI", Asio asio "ASIO")`,
/// this macro should expand to:
///
// This sample code block is marked as text because it's not a valid test,
// it's just illustrative. (see rust issue #96573)
/// ```text
/// pub enum HostId {
/// Wasapi,
/// Asio,
/// }
///
/// pub enum Host {
/// Wasapi(crate::host::wasapi::Host),
/// Asio(crate::host::asio::Host),
/// }
/// ```
///
/// And so on for Device, Devices, Host, Stream, SupportedInputConfigs,
/// SupportedOutputConfigs and all their necessary trait implementations.
///
macro_rules! impl_platform_host {
($($(#[cfg($feat: meta)])? $HostVariant:ident $host_mod:ident $host_name:literal),*) => {
/// 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.
///
/// 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
/// be acquired via the **ALL_HOSTS** const, and the **available_hosts** function.
/// 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.
pub struct Host(HostInner);
/// The **Device** implementation associated with the platform's dynamically dispatched
/// **Host** type.
/// The `Device` implementation associated with the platform's dynamically dispatched
/// [`Host`] type.
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.
pub struct Devices(DevicesInner);
/// The **Stream** implementation associated with the platform's dynamically dispatched
/// **Host** type.
/// The `Stream` implementation associated with the platform's dynamically dispatched
/// [`Host`] type.
// 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
// functions within the callback.
@ -68,12 +70,12 @@ macro_rules! impl_platform_host {
// TODO: Confirm this and add more specific detail and references.
pub struct Stream(StreamInner, crate::platform::NotSendSyncAcrossAllPlatforms);
/// The **SupportedInputConfigs** iterator associated with the platform's dynamically
/// dispatched **Host** type.
/// The `SupportedInputConfigs` iterator associated with the platform's dynamically
/// dispatched [`Host`] type.
pub struct SupportedInputConfigs(SupportedInputConfigsInner);
/// The **SupportedOutputConfigs** iterator associated with the platform's dynamically
/// dispatched **Host** type.
/// The `SupportedOutputConfigs` iterator associated with the platform's dynamically
/// dispatched [`Host`] type.
pub struct SupportedOutputConfigs(SupportedOutputConfigsInner);
/// 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 {
$(
$(#[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 {
$(
$(#[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 {
$(
$(#[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 {
$(
$(#[cfg($feat)])?
@ -181,7 +183,7 @@ macro_rules! impl_platform_host {
}
impl Host {
/// The unique identifier associated with this host.
/// The unique identifier associated with this `Host`.
pub fn id(&self) -> HostId {
match self.0 {
$(

View file

@ -9,7 +9,7 @@ use crate::{
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
/// 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
/// less readily available by default in many Linux distributions and is known to be tricky to
/// set up.
///
/// [`Host`]: crate::Host
pub trait HostTrait {
/// The type used for enumerating available devices by the host.
type Devices: Iterator<Item = Self::Device>;
@ -37,7 +39,7 @@ pub trait HostTrait {
/// Whether or not the host is available on the system.
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.
fn devices(&self) -> Result<Self::Devices, DevicesError>;
@ -90,7 +92,10 @@ pub trait DeviceTrait {
type SupportedInputConfigs: Iterator<Item = SupportedStreamConfigRange>;
/// The iterator type yielding supported output stream formats.
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;
/// The human-readable name of the device.
@ -199,7 +204,7 @@ pub trait DeviceTrait {
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 {
/// Run the stream.
///