From 7e17373e3158a960bad3d31916a6cab6a0dc3c4a Mon Sep 17 00:00:00 2001 From: alichay Date: Fri, 4 Nov 2022 15:57:23 -0500 Subject: [PATCH] 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 --- src/error.rs | 24 +++++------ src/lib.rs | 99 ++++++++++++++++++++++++++------------------- src/platform/mod.rs | 88 ++++++++++++++++++++-------------------- src/traits.rs | 13 ++++-- 4 files changed, 124 insertions(+), 100 deletions(-) diff --git a/src/error.rs b/src/error.rs index 31a8993..16f9003 100644 --- a/src/error.rs +++ b/src/error.rs @@ -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] diff --git a/src/lib.rs b/src/lib.rs index 7ba1395..1853ca3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -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` 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.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 diff --git a/src/platform/mod.rs b/src/platform/mod.rs index 22a0511..3b566f1 100644 --- a/src/platform/mod.rs +++ b/src/platform/mod.rs @@ -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 { $( diff --git a/src/traits.rs b/src/traits.rs index f079dae..6f5ff45 100644 --- a/src/traits.rs +++ b/src/traits.rs @@ -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; @@ -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; @@ -90,7 +92,10 @@ pub trait DeviceTrait { type SupportedInputConfigs: Iterator; /// The iterator type yielding supported output stream formats. type SupportedOutputConfigs: Iterator; - /// 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. ///