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.

src/tracks/command.rs

@@ -6,8 +6,9 @@ use tokio::sync::oneshot::Sender as OneshotSender;
 /// A request from external code using a [`TrackHandle`] to modify
 /// or act upon an [`Track`] object.
 ///
-/// [`Track`]: struct.Track.html
-/// [`TrackHandle`]: struct.TrackHandle.html
+/// [`Track`]: Track
+/// [`TrackHandle`]: TrackHandle
+#[non_exhaustive]
 pub enum TrackCommand {
     /// Set the track's play_mode to play/resume.
     Play,

src/tracks/handle.rs

@@ -15,7 +15,7 @@ use uuid::Uuid;
 /// the underlying [`Track`] object has been discarded. Those which aren't refer
 /// to immutable properties of the underlying stream.
 ///
-/// [`Track`]: struct.Track.html
+/// [`Track`]: Track
 pub struct TrackHandle {
     command_channel: UnboundedSender<TrackCommand>,
     seekable: bool,
@@ -26,7 +26,7 @@ impl TrackHandle {
     /// Creates a new handle, using the given command sink and hint as to whether
     /// the underlying [`Input`] supports seek operations.
     ///
-    /// [`Input`]: ../input/struct.Input.html
+    /// [`Input`]: crate::input::Input
     pub fn new(command_channel: UnboundedSender<TrackCommand>, seekable: bool, uuid: Uuid) -> Self {
         Self {
             command_channel,
@@ -50,7 +50,7 @@ impl TrackHandle {
     /// This is *final*, and will cause the audio context to fire
     /// a [`TrackEvent::End`] event.
     ///
-    /// [`TrackEvent::End`]: ../events/enum.TrackEvent.html#variant.End
+    /// [`TrackEvent::End`]: crate::events::TrackEvent::End
     pub fn stop(&self) -> TrackResult {
         self.send(TrackCommand::Stop)
     }
@@ -62,11 +62,11 @@ impl TrackHandle {
 
     /// Denotes whether the underlying [`Input`] stream is compatible with arbitrary seeking.
     ///
-    /// If this returns `false`, all calls to [`seek`] will fail, and the track is
+    /// If this returns `false`, all calls to [`seek_time`] will fail, and the track is
     /// incapable of looping.
     ///
-    /// [`seek`]: #method.seek
-    /// [`Input`]: ../input/struct.Input.html
+    /// [`seek_time`]: TrackHandle::seek_time
+    /// [`Input`]: crate::input::Input
     pub fn is_seekable(&self) -> bool {
         self.seekable
     }
@@ -76,7 +76,7 @@ impl TrackHandle {
     /// If the underlying [`Input`] does not support this behaviour,
     /// then all calls will fail.
     ///
-    /// [`Input`]: ../input/struct.Input.html
+    /// [`Input`]: crate::input::Input
     pub fn seek_time(&self, position: Duration) -> TrackResult {
         if self.seekable {
             self.send(TrackCommand::Seek(position))
@@ -91,8 +91,8 @@ impl TrackHandle {
     /// within the supplied function or closure. *Taking excess time could prevent
     /// timely sending of packets, causing audio glitches and delays*.
     ///
-    /// [`Track`]: struct.Track.html
-    /// [`EventContext::Track`]: ../events/enum.EventContext.html#variant.Track
+    /// [`Track`]: Track
+    /// [`EventContext::Track`]: crate::events::EventContext::Track
     pub fn add_event<F: EventHandler + 'static>(&self, event: Event, action: F) -> TrackResult {
         let cmd = TrackCommand::AddEvent(EventData::new(event, action));
         if event.is_global_only() {
@@ -108,7 +108,7 @@ impl TrackHandle {
     /// within the supplied function or closure. *Taking excess time could prevent
     /// timely sending of packets, causing audio glitches and delays*.
     ///
-    /// [`Track`]: struct.Track.html
+    /// [`Track`]: Track
     pub fn action<F>(&self, action: F) -> TrackResult
     where
         F: FnOnce(&mut Track) + Send + Sync + 'static,
@@ -160,7 +160,7 @@ impl TrackHandle {
     #[inline]
     /// Send a raw command to the [`Track`] object.
     ///
-    /// [`Track`]: struct.Track.html
+    /// [`Track`]: Track
     pub fn send(&self, cmd: TrackCommand) -> TrackResult {
         self.command_channel.send(cmd)
     }

src/tracks/looping.rs

@@ -1,7 +1,7 @@
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
 /// Looping behaviour for a [`Track`].
 ///
 /// [`Track`]: struct.Track.html
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub enum LoopState {
     /// Track will loop endlessly until loop state is changed or
     /// manually stopped.
@@ -11,7 +11,7 @@ pub enum LoopState {
     ///
     /// `Finite(0)` is the `Default`, stopping the track once its [`Input`] ends.
     ///
-    /// [`Input`]: ../input/struct.Input.html
+    /// [`Input`]: crate::input::Input
     Finite(usize),
 }
 

src/tracks/mod.rs

@@ -361,8 +361,8 @@ impl Track {
 /// Typically, this would be used if you wished to directly work on or configure
 /// the [`Track`] object before it is passed over to the driver.
 ///
-/// [`Track`]: struct.Track.html
-/// [`TrackHandle`]: struct.TrackHandle.html
+/// [`Track`]: Track
+/// [`TrackHandle`]: TrackHandle
 pub fn create_player(source: Input) -> (Track, TrackHandle) {
     let (tx, rx) = mpsc::unbounded_channel();
     let can_seek = source.is_seekable();
@@ -378,7 +378,7 @@ pub fn create_player(source: Input) -> (Track, TrackHandle) {
 /// Failure indicates that the accessed audio object has been
 /// removed or deleted by the audio context.
 ///
-/// [`TrackHandle`]: struct.TrackHandle.html
+/// [`TrackHandle`]: TrackHandle
 pub type TrackResult = Result<(), SendError<TrackCommand>>;
 
 /// Alias for return value from calls to [`TrackHandle::get_info`].
@@ -389,5 +389,5 @@ pub type TrackResult = Result<(), SendError<TrackCommand>>;
 /// Failure indicates that the accessed audio object has been
 /// removed or deleted by the audio context.
 ///
-/// [`TrackHandle::get_info`]: struct.TrackHandle.html#method.get_info
+/// [`TrackHandle::get_info`]: TrackHandle::get_info
 pub type TrackQueryResult = Result<OneshotReceiver<Box<TrackState>>, SendError<TrackCommand>>;

src/tracks/mode.rs

@@ -1,5 +1,6 @@
-#[derive(Clone, Copy, Debug, Eq, PartialEq)]
 /// Playback status of a track.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[non_exhaustive]
 pub enum PlayMode {
     /// The track is currently playing.
     Play,

src/tracks/queue.rs

@@ -53,8 +53,8 @@ use tracing::{info, warn};
 /// # };
 /// ```
 ///
-/// [`TrackEvent`]: ../events/enum.TrackEvent.html
-/// [`Driver::queue`]: ../driver/struct.Driver.html#method.queue
+/// [`TrackEvent`]: crate::events::TrackEvent
+/// [`Driver::queue`]: crate::driver::Driver::queue
 #[derive(Clone, Debug, Default)]
 pub struct TrackQueue {
     // NOTE: the choice of a parking lot mutex is quite deliberate
@@ -88,7 +88,7 @@ impl Queued {
 /// This abstracts away thread-safety from the user,
 /// and offers a convenient location to store further state if required.
 ///
-/// [`TrackQueue`]: struct.TrackQueue.html
+/// [`TrackQueue`]: TrackQueue
 struct TrackQueueCore {
     tracks: VecDeque<Queued>,
 }
@@ -163,11 +163,11 @@ impl TrackQueue {
 
     /// Adds a [`Track`] object to the queue, to be played in the channel managed by `handler`.
     ///
-    /// This is used with [`voice::create_player`] if additional configuration or event handlers
+    /// This is used with [`create_player`] if additional configuration or event handlers
     /// are required before enqueueing the audio track.
     ///
-    /// [`Track`]: struct.Track.html
-    /// [`voice::create_player`]: fn.create_player.html
+    /// [`Track`]: Track
+    /// [`create_player`]: super::create_player
     pub fn add(&self, mut track: Track, handler: &mut Driver) {
         self.add_raw(&mut track);
         handler.play(track);
@@ -208,7 +208,7 @@ impl TrackQueue {
     ///
     /// The returned entry can be readded to *this* queue via [`modify_queue`].
     ///
-    /// [`modify_queue`]: #method.modify_queue
+    /// [`modify_queue`]: TrackQueue::modify_queue
     pub fn dequeue(&self, index: usize) -> Option<Queued> {
         self.modify_queue(|vq| vq.remove(index))
     }
@@ -285,7 +285,7 @@ impl TrackQueue {
     ///
     /// Use [`modify_queue`] for direct modification of the queue.
     ///
-    /// [`modify_queue`]: #method.modify_queue
+    /// [`modify_queue`]: TrackQueue::modify_queue
     pub fn current_queue(&self) -> Vec<TrackHandle> {
         let inner = self.inner.lock();
 

src/tracks/state.rs

@@ -1,12 +1,10 @@
 use super::*;
 
 /// State of an [`Track`] object, designed to be passed to event handlers
-/// and retrieved remotely via [`TrackHandle::get_info`] or
-/// [`TrackHandle::get_info_blocking`].
+/// and retrieved remotely via [`TrackHandle::get_info`].
 ///
-/// [`Track`]: struct.Track.html
-/// [`TrackHandle::get_info`]: struct.TrackHandle.html#method.get_info
-/// [`TrackHandle::get_info_blocking`]: struct.TrackHandle.html#method.get_info_blocking
+/// [`Track`]: Track
+/// [`TrackHandle::get_info`]: TrackHandle::get_info
 #[derive(Copy, Clone, Debug, Default, PartialEq)]
 pub struct TrackState {
     /// Play status (e.g., active, paused, stopped) of this track.
@@ -15,7 +13,8 @@ pub struct TrackState {
     pub volume: f32,
     /// Current playback position in the source.
     ///
-    /// This is altered by loops and seeks
+    /// This is altered by loops and seeks, and represents this track's
+    /// position in its underlying input stream.
     pub position: Duration,
     /// Total playback time, increasing monotonically.
     pub play_time: Duration,