Docs: Move to new intra-doc links, make events non-exhaustive. (#19)

Far cleaner and more reliable than the old doc-link pattern. Also allowed me to spot some event types and sources which should have been made non_exhaustive.
2020-11-24 19:52:23 +00:00
parent 1ada46d24b
commit 94157b12bc
32 changed files with 169 additions and 166 deletions
--- a/src/input/cached/compressed.rs
+++ b/src/input/cached/compressed.rs
@@ -43,9 +43,9 @@ use tracing::{debug, trace};
 /// retrieved as **compressed Opus audio**. There is an associated memory cost,
 /// but this is far smaller than using a [`Memory`].
 ///
-/// [`Input`]: ../struct.Input.html
-/// [`Memory`]: struct.Memory.html
-/// [`Restartable`]: ../struct.Restartable.html
+/// [`Input`]: Input
+/// [`Memory`]: super::Memory
+/// [`Restartable`]: crate::input::restartable::Restartable
 #[derive(Clone, Debug)]
 pub struct Compressed {
    /// Inner shared bytestore.
@@ -59,7 +59,7 @@ pub struct Compressed {
 impl Compressed {
    /// Wrap an existing [`Input`] with an in-memory store, compressed using Opus.
    ///
-    /// [`Input`]: ../struct.Input.html
+    /// [`Input`]: Input
    /// [`Metadata.duration`]: ../struct.Metadata.html#structfield.duration
    pub fn new(source: Input, bitrate: Bitrate) -> Result<Self> {
        Self::with_config(source, bitrate, None)
@@ -69,10 +69,10 @@ impl Compressed {
    ///
    /// `config.length_hint` may be used to control the size of the initial chunk, preventing
    /// needless allocations and copies. If this is not present, the value specified in
-    /// `source`'s [`Metadata.duration`] will be used.
+    /// `source`'s [`Metadata::duration`] will be used.
    ///
-    /// [`Input`]: ../struct.Input.html
-    /// [`Metadata.duration`]: ../struct.Metadata.html#structfield.duration
+    /// [`Input`]: Input
+    /// [`Metadata::duration`]: crate::input::Metadata::duration
    pub fn with_config(source: Input, bitrate: Bitrate, config: Option<Config>) -> Result<Self> {
        let channels = if source.stereo {
            Channels::Stereo
@@ -92,8 +92,8 @@ impl Compressed {
    /// `length_hint` functions as in [`new`]. This function's behaviour is undefined if your encoder
    /// has a different sample rate than 48kHz, and if the decoder has a different channel count from the source.
    ///
-    /// [`Input`]: ../struct.Input.html
-    /// [`new`]: #method.new
+    /// [`Input`]: Input
+    /// [`new`]: Compressed::new
    pub fn with_encoder(
        mut source: Input,
        encoder: OpusEncoder,
@@ -154,7 +154,7 @@ impl From<Compressed> for Input {
 ///
 /// Created and managed by [`Compressed`].
 ///
-/// [`Compressed`]: struct.Compressed.html
+/// [`Compressed`]: Compressed
 #[derive(Debug)]
 pub struct OpusCompressor {
    encoder: OpusEncoder,
--- a/src/input/cached/memory.rs
+++ b/src/input/cached/memory.rs
@@ -25,9 +25,9 @@ use streamcatcher::{Catcher, Config};
 /// cost of audio processing. This is a significant *3 Mbps (375 kiB/s)*,
 /// or 131 MiB of RAM for a 6 minute song.
 ///
-/// [`Input`]: ../struct.Input.html
-/// [`Compressed`]: struct.Compressed.html
-/// [`Restartable`]: ../struct.Restartable.html
+/// [`Input`]: Input
+/// [`Compressed`]: super::Compressed
+/// [`Restartable`]: crate::input::restartable::Restartable
 #[derive(Clone, Debug)]
 pub struct Memory {
    /// Inner shared bytestore.
@@ -45,7 +45,7 @@ pub struct Memory {
 impl Memory {
    /// Wrap an existing [`Input`] with an in-memory store with the same codec and framing.
    ///
-    /// [`Input`]: ../struct.Input.html
+    /// [`Input`]: Input
    pub fn new(source: Input) -> Result<Self> {
        Self::with_config(source, None)
    }
@@ -54,10 +54,10 @@ impl Memory {
    ///
    /// `length_hint` may be used to control the size of the initial chunk, preventing
    /// needless allocations and copies. If this is not present, the value specified in
-    /// `source`'s [`Metadata.duration`] will be used, assuming that the source is uncompressed.
+    /// `source`'s [`Metadata::duration`] will be used, assuming that the source is uncompressed.
    ///
-    /// [`Input`]: ../struct.Input.html
-    /// [`Metadata.duration`]: ../struct.Metadata.html#structfield.duration
+    /// [`Input`]: Input
+    /// [`Metadata::duration`]: crate::input::Metadata::duration
    pub fn with_config(mut source: Input, config: Option<Config>) -> Result<Self> {
        let stereo = source.stereo;
        let kind = (&source.kind).into();
--- a/src/input/codec/mod.rs
+++ b/src/input/codec/mod.rs
@@ -9,7 +9,7 @@ use std::{fmt::Debug, mem};

 /// State used to decode input bytes of an [`Input`].
 ///
-/// [`Input`]: ../struct.Input.html
+/// [`Input`]: Input
 #[non_exhaustive]
 #[derive(Clone, Debug)]
 pub enum Codec {
@@ -18,19 +18,19 @@ pub enum Codec {
    ///
    /// Must be combined with a non-[`Raw`] container.
    ///
-    /// [`Raw`]: ../enum.Container.html#variant.Raw
+    /// [`Raw`]: Container::Raw
    Opus(OpusDecoderState),
    /// The inner bytestream is encoded using raw `i16` samples.
    ///
    /// Must be combined with a [`Raw`] container.
    ///
-    /// [`Raw`]: ../enum.Container.html#variant.Raw
+    /// [`Raw`]: Container::Raw
    Pcm,
    /// The inner bytestream is encoded using raw `f32` samples.
    ///
    /// Must be combined with a [`Raw`] container.
    ///
-    /// [`Raw`]: ../enum.Container.html#variant.Raw
+    /// [`Raw`]: Container::Raw
    FloatPcm,
 }

@@ -48,7 +48,7 @@ impl From<&Codec> for CodecType {

 /// Type of data being passed into an [`Input`].
 ///
-/// [`Input`]: ../struct.Input.html
+/// [`Input`]: Input
 #[non_exhaustive]
 #[derive(Copy, Clone, Debug)]
 pub enum CodecType {
@@ -56,19 +56,19 @@ pub enum CodecType {
    ///
    /// Must be combined with a non-[`Raw`] container.
    ///
-    /// [`Raw`]: ../enum.Container.html#variant.Raw
+    /// [`Raw`]: Container::Raw
    Opus,
    /// The inner bytestream is encoded using raw `i16` samples.
    ///
    /// Must be combined with a [`Raw`] container.
    ///
-    /// [`Raw`]: ../enum.Container.html#variant.Raw
+    /// [`Raw`]: Container::Raw
    Pcm,
    /// The inner bytestream is encoded using raw `f32` samples.
    ///
    /// Must be combined with a [`Raw`] container.
    ///
-    /// [`Raw`]: ../enum.Container.html#variant.Raw
+    /// [`Raw`]: Container::Raw
    FloatPcm,
 }

--- a/src/input/codec/opus.rs
+++ b/src/input/codec/opus.rs
@@ -4,7 +4,7 @@ use parking_lot::Mutex;
 use std::sync::Arc;

 #[derive(Clone, Debug)]
-/// Inner state
+/// Inner state used to decode Opus input sources.
 pub struct OpusDecoderState {
    /// Inner decoder used to convert opus frames into a stream of samples.
    pub decoder: Arc<Mutex<OpusDecoder>>,
--- a/src/input/error.rs
+++ b/src/input/error.rs
@@ -7,7 +7,7 @@ use streamcatcher::CatcherError;

 /// An error returned when creating a new [`Input`].
 ///
-/// [`Input`]: ../struct.Input.html
+/// [`Input`]: crate::input::Input
 #[derive(Debug)]
 #[non_exhaustive]
 pub enum Error {
@@ -71,7 +71,7 @@ impl From<OpusError> for Error {

 /// An error returned from the [`dca`] method.
 ///
-/// [`dca`]: ../fn.dca.html
+/// [`dca`]: crate::input::dca
 #[derive(Debug)]
 #[non_exhaustive]
 pub enum DcaError {
@@ -89,5 +89,5 @@ pub enum DcaError {

 /// Convenience type for fallible return of [`Input`]s.
 ///
-/// [`Input`]: ../struct.Input.html
+/// [`Input`]: crate::input::Input
 pub type Result<T> = std::result::Result<T, Error>;
--- a/src/input/ffmpeg_src.rs
+++ b/src/input/ffmpeg_src.rs
@@ -71,7 +71,9 @@ pub(crate) async fn _ffmpeg(path: &OsStr) -> Result<Input> {
 ///     "pcm_s16le",
 ///     "-",
 /// ]));
-///```
+/// ```
+///
+/// [`ffmpeg`]: ffmpeg
 pub async fn ffmpeg_optioned<P: AsRef<OsStr>>(
    path: P,
    pre_input_args: &[&str],
--- a/src/input/metadata.rs
+++ b/src/input/metadata.rs
@@ -4,7 +4,7 @@ use std::time::Duration;

 /// Information about an [`Input`] source.
 ///
-/// [`Input`]: struct.Input.html
+/// [`Input`]: crate::input::Input
 #[derive(Clone, Debug, Default, Eq, PartialEq)]
 pub struct Metadata {
    /// The title of this stream.
@@ -95,7 +95,7 @@ impl Metadata {
        }
    }

-    /// Use `youtube-dl` to extract metadata for an online resource.
+    /// Use `youtube-dl`'s JSON output for metadata for an online resource.
    pub fn from_ytdl_output(value: Value) -> Self {
        let obj = value.as_object();

--- a/src/input/mod.rs
+++ b/src/input/mod.rs
@@ -20,13 +20,13 @@
 //!  * its [`Input`] [meets the promises described herein](codec/struct.OpusDecoderState.html#structfield.allow_passthrough),
 //!  * and that track's volume is set to `1.0`.
 //!
-//! [`Input`]: struct.Input.html
-//! [`Reader`]: reader/enum.Reader.html
-//! [`Container`]: enum.Container.html
-//! [`Codec`]: codec/enum.Codec.html
+//! [`Input`]: Input
+//! [`Reader`]: reader::Reader
+//! [`Container`]: Container
+//! [`Codec`]: Codec
 //! [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
-//! [`Compressed`]: cached/struct.Compressed.html
-//! [`dca`]: fn.dca.html
+//! [`Compressed`]: cached::Compressed
+//! [`dca`]: dca()

 pub mod cached;
 mod child;
@@ -80,8 +80,8 @@ use tracing::{debug, error};
 ///
 /// See the [module root] for more information.
 ///
-/// [`Reader`]: enum.Reader.html
-/// [module root]: index.html
+/// [`Reader`]: Reader
+/// [module root]: super
 #[derive(Debug)]
 pub struct Input {
    /// Information about the played source.
@@ -130,7 +130,7 @@ impl Input {

    /// Returns whether the inner [`Reader`] implements [`Seek`].
    ///
-    /// [`Reader`]: reader/enum.Reader.html
+    /// [`Reader`]: reader::Reader
    /// [`Seek`]: https://doc.rust-lang.org/std/io/trait.Seek.html
    pub fn is_seekable(&self) -> bool {
        self.reader.is_seekable()
@@ -143,7 +143,7 @@ impl Input {

    /// Returns the type of the inner [`Codec`].
    ///
-    /// [`Codec`]: codec/enum.Codec.html
+    /// [`Codec`]: Codec
    pub fn get_type(&self) -> CodecType {
        (&self.kind).into()
    }
--- a/src/input/reader.rs
+++ b/src/input/reader.rs
@@ -23,14 +23,14 @@ use streamcatcher::{Catcher, TxCatcher};
 /// Users may define their own data sources using [`Extension`]
 /// and [`ExtensionSeek`].
 ///
-/// [`Extension`]: #variant.Extension
-/// [`ExtensionSeek`]: #variant.ExtensionSeek
+/// [`Extension`]: Reader::Extension
+/// [`ExtensionSeek`]: Reader::ExtensionSeek
 pub enum Reader {
    /// Piped output of another program (i.e., [`ffmpeg`]).
    ///
    /// Does not support seeking.
    ///
-    /// [`ffmpeg`]: ../fn.ffmpeg.html
+    /// [`ffmpeg`]: super::ffmpeg
    Pipe(BufReader<ChildContainer>),
    /// A cached, raw in-memory store, provided by Songbird.
    ///
--- a/src/input/restartable.rs
+++ b/src/input/restartable.rs
@@ -37,9 +37,9 @@ type RecreateChannel = Receiver<Result<(Box<Input>, Recreator)>>;
 /// cannot be spared. Forward seeks will drain the track until reaching
 /// the desired timestamp.
 ///
-/// [`Input`]: struct.Input.html
-/// [`Memory`]: cached/struct.Memory.html
-/// [`Compressed`]: cached/struct.Compressed.html
+/// [`Input`]: Input
+/// [`Memory`]: cached::Memory
+/// [`Compressed`]: cached::Compressed
 pub struct Restartable {
    async_handle: Option<Handle>,
    awaiting_source: Option<RecreateChannel>,
@@ -89,7 +89,7 @@ impl Restartable {
 /// Trait used to create an instance of a [`Reader`] at instantiation and when
 /// a backwards seek is needed.
 ///
-/// [`Reader`]: ../reader/enum.Reader.html
+/// [`Reader`]: reader::Reader
 #[async_trait]
 pub trait Restart {
    /// Tries to create a replacement source.