Docs: Fix module docs for songbird::tracks.

Module docs mistakenly used the old doc-link format, so removing `create_player` never fired an error! These have also been partially rewritten to explain the role of `Track` and `TrackHandle`.

Includes some other misc fixes to links, mention of `TrackHandle::action` for metadata handling, etc.

Closes #140.

README.md

@@ -1,4 +1,4 @@
-[![docs-badge][]][docs] [![build badge]][build] [![guild-badge][]][guild] [![crates.io version]][crates.io link] [![rust 1.61.0+ badge]][rust 1.61.0+ link]
+[![docs-badge][]][docs] [![next-docs-badge][]][next-docs] [![build badge]][build] [![guild-badge][]][guild] [![crates.io version]][crates.io link] [![rust 1.61.0+ badge]][rust 1.61.0+ link]
 
 # Songbird
 
@@ -86,9 +86,12 @@ Songbird's logo is based upon the copyright-free image ["Black-Capped Chickadee"
 [build badge]: https://img.shields.io/github/workflow/status/serenity-rs/songbird/CI?style=flat-square
 [build]: https://github.com/serenity-rs/songbird/actions
 
-[docs-badge]: https://img.shields.io/badge/docs-online-4d76ae.svg?style=flat-square
+[docs-badge]: https://img.shields.io/badge/docs-current-4d76ae.svg?style=flat-square
 [docs]: https://serenity-rs.github.io/songbird/current
 
+[next-docs-badge]: https://img.shields.io/badge/docs-next-4d76ae.svg?style=flat-square
+[next-docs]: https://serenity-rs.github.io/songbird/next
+
 [guild]: https://discord.gg/9X7vCus
 [guild-badge]: https://img.shields.io/discord/381880193251409931.svg?style=flat-square&colorB=7289DA
 

src/input/mod.rs

@@ -144,6 +144,8 @@ use tokio::runtime::Handle as TokioHandle;
 ///
 /// // If we want to inspect metadata (and we can't use AuxMetadata for any reason), we have
 /// // to parse the track ourselves.
+/// //
+/// // We can access it on a live track using `TrackHandle::action()`.
 /// in_memory_input = in_memory_input
 ///     .make_playable_async(&CODEC_REGISTRY, &PROBE)
 ///     .await

src/serenity.rs

@@ -1,7 +1,7 @@
-//! Compatability and convenience methods for working with [serenity].
+//! Compatibility and convenience methods for working with [serenity].
 //! Requires the `"serenity"` feature.
 //!
-//! [serenity]: https://crates.io/crates/serenity/0.9.0-rc.2
+//! [serenity]: https://crates.io/crates/serenity
 
 use crate::{Config, Songbird};
 use serenity::{

src/tracks/handle.rs

@@ -15,8 +15,6 @@ use uuid::Uuid;
 /// Many method calls here are fallible; in most cases, this will be because
 /// the underlying [`Track`] object has been discarded. Those which aren't refer
 /// to shared data not used by the driver.
-///
-/// [`Track`]: Track
 pub struct TrackHandle {
     inner: Arc<InnerHandle>,
 }

src/tracks/mod.rs

@@ -1,18 +1,20 @@
 //! Live, controllable audio instances.
 //!
 //! Tracks add control and event data around the bytestreams offered by [`Input`],
-//! where each represents a live audio source inside of the driver's mixer.
+//! where each represents a live audio source inside of the driver's mixer. This includes
+//! play state, volume, and looping behaviour.
 //!
-//! To prevent locking and stalling of the driver, tracks are controlled from your bot using a
+//! To configure an audio source as it is created, you can create a [`Track`] to set the
-//! [`TrackHandle`]. These handles remotely send commands from your bot's (a)sync
+//! above playback state [from any `Input` or `T: Into<Input>`](Track#trait-implementations)
-//! context to control playback, register events, and execute synchronous closures.
+//! using `Track::from(...)`.
 //!
-//! If you want a new track from an [`Input`], i.e., for direct control before
+//! To configure an audio source once it has been given to a [`Driver`], you are given a
-//! playing your source on the driver, use [`create_player`].
+//! [`TrackHandle`] once you hand the [`Input`] and state over to be played. These handles
+//! remotely send commands from your bot's (a)sync context to control playback, register events,
+//! and execute synchronous closures. This design prevents user code from being able to lock
+//! or stall the audio mixer.
 //!
-//! [`Input`]: ../input/struct.Input.html
+//! [`Driver`]: crate::driver::Driver
-//! [`TrackHandle`]: struct.TrackHandle.html
-//! [`create_player`]: fn.create_player.html
 
 mod action;
 mod command;
@@ -47,7 +49,7 @@ use uuid::Uuid;
 /// [`Track`]s allow you to configure play modes, volume, event handlers, and other track state
 /// before you pass an input to the [`Driver`].
 ///
-/// Live track data is accesseed via a [`TrackHandle`], returned by [`Driver::play`] and
+/// Live track data is accessed via a [`TrackHandle`], which is returned by [`Driver::play`] and
 /// related methods.
 ///
 /// # Example
@@ -55,15 +57,13 @@ use uuid::Uuid;
 /// ```rust,no_run
 /// use songbird::{driver::Driver, input::File, tracks::Track};
 ///
-/// # async {
 /// // A Call is also valid here!
-/// let mut handler: Driver = Default::default();
+/// let mut driver: Driver = Default::default();
 /// let source = File::new("../audio/my-favourite-song.mp3");
 ///
-/// handler.play_only(Track::new(source.into()).volume(0.5));
+/// let handle = driver.play_only(Track::from(source).volume(0.5));
 ///
-/// // Future access occurs via audio_handle.
+/// // Future access occurs via audio.
-/// # };
 /// ```
 ///
 /// [`Driver`]: crate::driver::Driver