Docs: Move to new intra-doc links, make events non-exhaustive. (seren…

…ity-rs#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/driver/config.rs

@@ -12,7 +12,7 @@ pub struct Config {
     /// driver is actively connected, but will apply to subsequent
     /// sessions.
     ///
-    /// [`CryptoMode::Normal`]: enum.CryptoMode.html#variant.Normal
+    /// [`CryptoMode::Normal`]: CryptoMode::Normal
     pub crypto_mode: CryptoMode,
     /// Configures whether decoding and decryption occur for all received packets.
     ///
@@ -24,10 +24,10 @@ pub struct Config {
     /// Defaults to [`DecodeMode::Decrypt`]. This is due to per-packet decoding costs,
     /// which most users will not want to pay, but allowing speaking events which are commonly used.
     ///
-    /// [`DecodeMode::Decode`]: enum.DecodeMode.html#variant.Decode
-    /// [`DecodeMode::Decrypt`]: enum.DecodeMode.html#variant.Decrypt
-    /// [`DecodeMode::Pass`]: enum.DecodeMode.html#variant.Pass
-    /// [user speaking events]: ../events/enum.CoreEvent.html#variant.SpeakingUpdate
+    /// [`DecodeMode::Decode`]: DecodeMode::Decode
+    /// [`DecodeMode::Decrypt`]: DecodeMode::Decrypt
+    /// [`DecodeMode::Pass`]: DecodeMode::Pass
+    /// [user speaking events]: crate::events::CoreEvent::SpeakingUpdate
     pub decode_mode: DecodeMode,
     /// Number of concurrently active tracks to allocate memory for.
     ///

src/driver/decode_mode.rs

@@ -12,7 +12,7 @@ pub enum DecodeMode {
     /// are not present, as they are encrypted.
     /// This event requires such functionality.*
     ///
-    /// [user speaking events]: ../events/enum.CoreEvent.html#variant.SpeakingUpdate
+    /// [user speaking events]: crate::events::CoreEvent::SpeakingUpdate
     Pass,
     /// Decrypts the body of each received packet.
     ///

src/driver/mod.rs

@@ -125,8 +125,8 @@ impl Driver {
     ///
     /// This can be a source created via [`ffmpeg`] or [`ytdl`].
     ///
-    /// [`ffmpeg`]: ../input/fn.ffmpeg.html
-    /// [`ytdl`]: ../input/fn.ytdl.html
+    /// [`ffmpeg`]: crate::input::ffmpeg
+    /// [`ytdl`]: crate::input::ytdl
     #[instrument(skip(self))]
     pub fn play_source(&mut self, source: Input) -> TrackHandle {
         let (player, handle) = super::create_player(source);
@@ -140,7 +140,7 @@ impl Driver {
     /// Unlike [`play_source`], this stops all other sources attached
     /// to the channel.
     ///
-    /// [`play_source`]: #method.play_source
+    /// [`play_source`]: Driver::play_source
     #[instrument(skip(self))]
     pub fn play_only_source(&mut self, source: Input) -> TrackHandle {
         let (player, handle) = super::create_player(source);
@@ -156,9 +156,9 @@ impl Driver {
     /// that this allows for direct manipulation of the [`Track`] object
     /// before it is passed over to the voice and mixing contexts.
     ///
-    /// [`create_player`]: ../tracks/fn.create_player.html
-    /// [`Track`]: ../tracks/struct.Track.html
-    /// [`play_source`]: #method.play_source
+    /// [`create_player`]: crate::tracks::create_player
+    /// [`create_player`]: crate::tracks::Track
+    /// [`play_source`]: Driver::play_source
     #[instrument(skip(self))]
     pub fn play(&mut self, track: Track) {
         self.send(CoreMessage::AddTrack(track));
@@ -171,10 +171,10 @@ impl Driver {
     /// channel. Like [`play`], however, this allows for direct manipulation of the
     /// [`Track`] object before it is passed over to the voice and mixing contexts.
     ///
-    /// [`create_player`]: ../tracks/fn.create_player.html
-    /// [`Track`]: ../tracks/struct.Track.html
-    /// [`play_only_source`]: #method.play_only_source
-    /// [`play`]: #method.play
+    /// [`create_player`]: crate::tracks::create_player
+    /// [`Track`]: crate::tracks::Track
+    /// [`play_only_source`]: Driver::play_only_source
+    /// [`play`]: Driver::play
     #[instrument(skip(self))]
     pub fn play_only(&mut self, track: Track) {
         self.send(CoreMessage::SetTrack(Some(track)));
@@ -216,9 +216,9 @@ impl Driver {
     /// within the supplied function or closure. *Taking excess time could prevent
     /// timely sending of packets, causing audio glitches and delays*.
     ///
-    /// [`Track`]: ../tracks/struct.Track.html
-    /// [`TrackEvent`]: ../events/enum.TrackEvent.html
-    /// [`EventContext`]: ../events/enum.EventContext.html
+    /// [`Track`]: crate::tracks::Track
+    /// [`TrackEvent`]: crate::events::TrackEvent
+    /// [`EventContext`]: crate::events::EventContext
     #[instrument(skip(self, action))]
     pub fn add_global_event<F: EventHandler + 'static>(&mut self, event: Event, action: F) {
         self.send(CoreMessage::AddEvent(EventData::new(event, action)));
@@ -243,8 +243,8 @@ impl Driver {
     /// Queue additions should be made via [`enqueue`] and
     /// [`enqueue_source`].
     ///
-    /// [`enqueue`]: #method.enqueue
-    /// [`enqueue_source`]: #method.enqueue_source
+    /// [`enqueue`]: Driver::enqueue
+    /// [`enqueue_source`]: Driver::enqueue_source
     pub fn queue(&self) -> &TrackQueue {
         &self.queue
     }
@@ -253,7 +253,7 @@ impl Driver {
     ///
     /// Requires the `"builtin-queue"` feature.
     ///
-    /// [`Input`]: ../input/struct.input.html
+    /// [`Input`]: crate::input::Input
     pub fn enqueue_source(&mut self, source: Input) {
         let (mut track, _) = tracks::create_player(source);
         self.queue.add_raw(&mut track);
@@ -264,7 +264,7 @@ impl Driver {
     ///
     /// Requires the `"builtin-queue"` feature.
     ///
-    /// [`Track`]: ../tracks/struct.track.html
+    /// [`Track`]: crate::tracks::Track
     pub fn enqueue(&mut self, mut track: Track) {
         self.queue.add_raw(&mut track);
         self.play(track);

src/error.rs

@@ -19,7 +19,7 @@ pub enum JoinError {
     NoSender,
     /// Tried to leave a [`Call`] which was not found.
     ///
-    /// [`Call`]: ../struct.Call.html
+    /// [`Call`]: crate::Call
     NoCall,
     #[cfg(feature = "serenity")]
     /// Serenity-specific WebSocket send error.

src/events/context.rs

@@ -8,17 +8,18 @@ use discortp::{rtcp::Rtcp, rtp::Rtp};
 /// Information about which tracks or data fired an event.
 ///
 /// [`Track`] events may be local or global, and have no tracks
-/// if fired on the global context via [`Handler::add_global_event`].
+/// if fired on the global context via [`Driver::add_global_event`].
 ///
-/// [`Track`]: ../tracks/struct.Track.html
-/// [`Handler::add_global_event`]: ../struct.Handler.html#method.add_global_event
+/// [`Track`]: crate::tracks::Track
+/// [`Driver::add_global_event`]: crate::driver::Driver::add_global_event
 #[derive(Clone, Debug)]
+#[non_exhaustive]
 pub enum EventContext<'a> {
     /// Track event context, passed to events created via [`TrackHandle::add_event`],
     /// [`EventStore::add_event`], or relevant global events.
     ///
-    /// [`EventStore::add_event`]: struct.EventStore.html#method.add_event
-    /// [`TrackHandle::add_event`]: ../tracks/struct.TrackHandle.html#method.add_event
+    /// [`EventStore::add_event`]: EventStore::add_event
+    /// [`TrackHandle::add_event`]: TrackHandle::add_event
     Track(&'a [(&'a TrackState, &'a TrackHandle)]),
     /// Speaking state update, typically describing how another voice
     /// user is transmitting audio data. Clients must send at least one such

src/events/core.rs

@@ -1,11 +1,12 @@
-#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
 /// Voice core events occur on receipt of
 /// voice packets and telemetry.
 ///
 /// Core events persist while the `action` in [`EventData`]
 /// returns `None`.
 ///
-/// [`EventData`]: struct.EventData.html
+/// [`EventData`]: super::EventData
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+#[non_exhaustive]
 pub enum CoreEvent {
     /// Fired on receipt of a speaking state update from another host.
     ///

src/events/data.rs

@@ -17,10 +17,10 @@ impl EventData {
     /// Event handlers will be re-added with their new trigger condition,
     /// or removed if [`Cancel`]led
     ///
-    /// [`EventContext`]: enum.EventContext.html
-    /// [`Event`]: enum.Event.html
-    /// [`Delayed`]: enum.Event.html#variant.Delayed
-    /// [`Cancel`]: enum.Event.html#variant.Cancel
+    /// [`EventContext`]: EventContext
+    /// [`Event`]: Event
+    /// [`Delayed`]: Event::Delayed
+    /// [`Cancel`]: Event::Cancel
     pub fn new<F: EventHandler + 'static>(event: Event, action: F) -> Self {
         Self {
             event,

src/events/mod.rs

@@ -12,16 +12,15 @@ pub use self::{context::*, core::*, data::*, store::*, track::*, untimed::*};
 use async_trait::async_trait;
 use std::time::Duration;
 
-#[async_trait]
 /// Trait to handle an event which can be fired per-track, or globally.
 ///
 /// These may be feasibly reused between several event sources.
+#[async_trait]
 pub trait EventHandler: Send + Sync {
     /// Respond to one received event.
     async fn act(&self, ctx: &EventContext<'_>) -> Option<Event>;
 }
 
-#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
 /// Classes of event which may occur, triggering a handler
 /// at the local (track-specific) or global level.
 ///
@@ -32,7 +31,9 @@ pub trait EventHandler: Send + Sync {
 ///
 /// Event handlers themselves are described in [`EventData::action`].
 ///
-/// [`EventData::action`]: struct.EventData.html#method.action
+/// [`EventData::action`]: EventData::action
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+#[non_exhaustive]
 pub enum Event {
     /// Periodic events rely upon two parameters: a *period*
     /// and an optional *phase*.
@@ -41,15 +42,15 @@ pub enum Event {
     /// in one *period*. Periodic events repeat automatically
     /// so long as the `action` in [`EventData`] returns `None`.
     ///
-    /// [`EventData`]: struct.EventData.html
+    /// [`EventData`]: EventData
     Periodic(Duration, Option<Duration>),
     /// Delayed events rely upon a *delay* parameter, and
     /// fire one *delay* after the audio context processes them.
     ///
     /// Delayed events are automatically removed once fired,
     /// so long as the `action` in [`EventData`] returns `None`.
     ///
-    /// [`EventData`]: struct.EventData.html
+    /// [`EventData`]: EventData
     Delayed(Duration),
     /// Track events correspond to certain actions or changes
     /// of state, such as a track finishing, looping, or being
@@ -58,15 +59,15 @@ pub enum Event {
     /// Track events persist while the `action` in [`EventData`]
     /// returns `None`.
     ///
-    /// [`EventData`]: struct.EventData.html
+    /// [`EventData`]: EventData
     Track(TrackEvent),
     /// Core events
     ///
     /// Track events persist while the `action` in [`EventData`]
     /// returns `None`. Core events **must** be applied globally,
     /// as attaching them to a track is a no-op.
     ///
-    /// [`EventData`]: struct.EventData.html
+    /// [`EventData`]: EventData
     Core(CoreEvent),
     /// Cancels the event, if it was intended to persist.
     Cancel,

src/events/store.rs

@@ -15,7 +15,7 @@ use tracing::info;
 /// Timed events are stored in a binary heap for fast selection, and have custom `Eq`,
 /// `Ord`, etc. implementations to support (only) this.
 ///
-/// [`EventData`]: struct.EventData.html
+/// [`EventData`]: EventData
 pub struct EventStore {
     timed: BinaryHeap<EventData>,
     untimed: HashMap<UntimedEvent, Vec<EventData>>,
@@ -33,7 +33,7 @@ impl EventStore {
     /// This is usually automatically installed by the driver once
     /// a track has been registered.
     ///
-    /// [`Track`]: ../tracks/struct.Track.html
+    /// [`Track`]: crate::tracks::Track
     pub fn new_local() -> Self {
         EventStore {
             local_only: true,
@@ -45,7 +45,7 @@ impl EventStore {
     ///
     /// Updates `evt` according to [`EventData::compute_activation`].
     ///
-    /// [`EventData::compute_activation`]: struct.EventData.html#method.compute_activation
+    /// [`EventData::compute_activation`]: EventData::compute_activation
     pub fn add_event(&mut self, mut evt: EventData, now: Duration) {
         evt.compute_activation(now);
 

src/events/track.rs

@@ -1,4 +1,3 @@
-#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
 /// Track events correspond to certain actions or changes
 /// of state, such as a track finishing, looping, or being
 /// manually stopped. Voice core events occur on receipt of
@@ -7,7 +6,9 @@
 /// Track events persist while the `action` in [`EventData`]
 /// returns `None`.
 ///
-/// [`EventData`]: struct.EventData.html
+/// [`EventData`]: super::EventData
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+#[non_exhaustive]
 pub enum TrackEvent {
     /// The attached track has ended.
     End,

src/events/untimed.rs

@@ -1,12 +1,13 @@
 use super::*;
 
-#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
 /// Track and voice core events.
 ///
 /// Untimed events persist while the `action` in [`EventData`]
 /// returns `None`.
 ///
-/// [`EventData`]: struct.EventData.html
+/// [`EventData`]: EventData
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+#[non_exhaustive]
 pub enum UntimedEvent {
     /// Untimed events belonging to a track, such as state changes, end, or loops.
     Track(TrackEvent),

src/handler.rs

@@ -29,8 +29,7 @@ enum Return {
 /// If the `"driver"` feature is enabled, then a Call exposes all control methods of
 /// [`Driver`] via `Deref(Mut)`.
 ///
-/// [`Driver`]: driver/struct.Driver.html
-/// [`Shard`]: ../gateway/struct.Shard.html
+/// [`Driver`]: struct@Driver
 #[derive(Clone, Debug)]
 pub struct Call {
     connection: Option<(ChannelId, ConnectionProgress, Return)>,
@@ -45,11 +44,14 @@ pub struct Call {
     /// Whether the current handler is set to mute voice connections.
     self_mute: bool,
     user_id: UserId,
-    /// Will be set when a `Call` is made via the [`new`][`Call::new`]
+    /// Will be set when a `Call` is made via the [`new`]
     /// method.
     ///
-    /// When set via [`standalone`][`Call::standalone`], it will not be
+    /// When set via [`standalone`](`Call::standalone`), it will not be
     /// present.
+    ///
+    /// [`new`]: Call::new
+    /// [`standalone`]: Call::standalone
     ws: Option<Shard>,
 }
 
@@ -153,7 +155,7 @@ impl Call {
     /// **Note**: If the `Call` was created via [`standalone`], then this
     /// will _only_ update whether the connection is internally deafened.
     ///
-    /// [`standalone`]: #method.standalone
+    /// [`standalone`]: Call::standalone
     #[instrument(skip(self))]
     pub async fn deafen(&mut self, deaf: bool) -> JoinResult<()> {
         self.self_deaf = deaf;
@@ -217,7 +219,7 @@ impl Call {
     /// will _only_ update whether the connection is internally connected to a
     /// voice channel.
     ///
-    /// [`standalone`]: #method.standalone
+    /// [`standalone`]: Call::standalone
     #[instrument(skip(self))]
     pub async fn leave(&mut self) -> JoinResult<()> {
         // Only send an update if we were in a voice channel.
@@ -237,7 +239,7 @@ impl Call {
     /// **Note**: If the `Call` was created via [`standalone`], then this
     /// will _only_ update whether the connection is internally muted.
     ///
-    /// [`standalone`]: #method.standalone
+    /// [`standalone`]: Call::standalone
     #[instrument(skip(self))]
     pub async fn mute(&mut self, mute: bool) -> JoinResult<()> {
         self.self_mute = mute;
@@ -259,11 +261,7 @@ impl Call {
     /// You should only need to use this if you initialized the `Call` via
     /// [`standalone`].
     ///
-    /// Refer to the documentation for [`connect`] for when this will
-    /// automatically connect to a voice channel.
-    ///
-    /// [`connect`]: #method.connect
-    /// [`standalone`]: #method.standalone
+    /// [`standalone`]: Call::standalone
     #[instrument(skip(self, token))]
     pub fn update_server(&mut self, endpoint: String, token: String) {
         let try_conn = if let Some((_, ref mut progress, _)) = self.connection.as_mut() {
@@ -282,11 +280,7 @@ impl Call {
     /// You should only need to use this if you initialized the `Call` via
     /// [`standalone`].
     ///
-    /// refer to the documentation for [`connect`] for when this will
-    /// automatically connect to a voice channel.
-    ///
-    /// [`connect`]: #method.connect
-    /// [`standalone`]: #method.standalone
+    /// [`standalone`]: Call::standalone
     #[instrument(skip(self))]
     pub fn update_state(&mut self, session_id: String) {
         let try_conn = if let Some((_, ref mut progress, _)) = self.connection.as_mut() {
@@ -304,7 +298,7 @@ impl Call {
     ///
     /// Does nothing if initialized via [`standalone`].
     ///
-    /// [`standalone`]: #method.standalone
+    /// [`standalone`]: Call::standalone
     #[instrument(skip(self))]
     async fn update(&mut self) -> JoinResult<()> {
         if let Some(ws) = self.ws.as_mut() {